@loopback/rest 4.0.0-alpha.8 → 5.0.1

package/src/router/regexp-router.ts

@@ -0,0 +1,104 @@
+// 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 {PathParameterValues} from '../types';
+import {toExpressPath} from './openapi-path';
+import {RestRouterOptions} from './rest-router';
+import {createResolvedRoute, ResolvedRoute, RouteEntry} from './route-entry';
+import {compareRoute} from './route-sort';
+import {BaseRouter} from './router-base';
+import {pathToRegexp, Key} from 'path-to-regexp';
+
+const debug = require('debug')('loopback:rest:router:regexp');
+
+/**
+ * Route entry with path-to-regexp
+ */
+interface RegExpRouteEntry extends RouteEntry {
+  regexp: RegExp;
+  keys: Key[];
+}
+
+/**
+ * Router implementation based on regexp matching
+ */
+export class RegExpRouter extends BaseRouter {
+  private routes: RegExpRouteEntry[] = [];
+
+  // Sort the routes based on their paths and variables
+  private _sorted: boolean;
+  private _sort() {
+    if (!this._sorted) {
+      this.routes.sort(compareRoute);
+      this._sorted = true;
+    }
+  }
+
+  constructor(
+    @inject(RestBindings.ROUTER_OPTIONS, {optional: true})
+    options?: RestRouterOptions,
+  ) {
+    super(options);
+  }
+
+  protected addRouteWithPathVars(route: RouteEntry) {
+    const path = toExpressPath(route.path);
+    const keys: Key[] = [];
+    const regexp = pathToRegexp(path, keys, {
+      strict: this.options.strict,
+      end: true,
+    });
+    const entry: RegExpRouteEntry = Object.assign(route, {keys, regexp});
+    this.routes.push(entry);
+    this._sorted = false;
+  }
+
+  protected findRouteWithPathVars(
+    verb: string,
+    path: string,
+  ): ResolvedRoute | undefined {
+    this._sort();
+    for (const r of this.routes) {
+      debug('trying endpoint %s', inspect(r, {depth: 5}));
+      if (r.verb !== verb.toLowerCase()) {
+        debug(' -> verb mismatch');
+        continue;
+      }
+
+      const match = r.regexp.exec(path);
+      if (!match) {
+        debug(' -> path mismatch');
+        continue;
+      }
+
+      const pathParams = this._buildPathParams(r, match);
+      debug(' -> found with params: %j', pathParams);
+
+      return createResolvedRoute(r, pathParams);
+    }
+    return undefined;
+  }
+
+  protected listRoutesWithPathVars() {
+    this._sort();
+    return this.routes;
+  }
+
+  private _buildPathParams(
+    route: RegExpRouteEntry,
+    pathMatch: RegExpExecArray,
+  ): PathParameterValues {
+    const pathParams: PathParameterValues = {};
+    for (const ix in route.keys) {
+      const key = route.keys[ix];
+      const matchIndex = +ix + 1;
+      pathParams[key.name] = pathMatch[matchIndex];
+    }
+    return pathParams;
+  }
+}

package/src/router/rest-router.ts

@@ -0,0 +1,48 @@
+// 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 {Request} from '../types';
+import {ResolvedRoute, RouteEntry} from './route-entry';
+
+/*
+/**
+ * Interface for router implementation
+ */
+export interface RestRouter {
+  /**
+   * Add a route to the router
+   * @param route - A route entry
+   */
+  add(route: RouteEntry): void;
+
+  /**
+   * Find a matching route for the given http request
+   * @param request - Http request
+   * @returns The resolved route, if not found, `undefined` is returned
+   */
+  find(request: Request): ResolvedRoute | undefined;
+
+  /**
+   * List all routes
+   */
+  list(): RouteEntry[];
+}
+
+export type RestRouterOptions = {
+  /**
+   * When `true` it uses trailing slash to match. (default: `false`)
+   *
+   * 1. `strict` is true:
+   * - request `/orders` matches route `/orders` but not `/orders/`
+   * - request `/orders/` matches route `/orders/` but not `/orders`
+   *
+   * 2. `strict` is false (default)
+   * - request `/orders` matches route `/orders` first and falls back to `/orders/`
+   * - request `/orders/` matches route `/orders/` first and falls back to `/orders`
+   *
+   * See `strict routing` at http://expressjs.com/en/4x/api.html#app
+   */
+  strict?: boolean;
+};

package/src/router/route-entry.ts

@@ -0,0 +1,74 @@
+// Copyright IBM Corp. 2018,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 {Context} from '@loopback/context';
+import {OperationObject, SchemasObject} from '@loopback/openapi-v3';
+import {OperationArgs, OperationRetval, PathParameterValues} from '../types';
+
+/**
+ * An entry in the routing table
+ */
+export interface RouteEntry {
+  /**
+   * http verb
+   */
+  readonly verb: string;
+  /**
+   * http path
+   */
+  readonly path: string;
+  /**
+   * OpenAPI operation spec
+   */
+  readonly spec: OperationObject;
+
+  /**
+   * Update bindings for the request context
+   * @param requestContext
+   */
+  updateBindings(requestContext: Context): void;
+
+  /**
+   * A handler to invoke the resolved controller method
+   * @param requestContext
+   * @param args
+   */
+  invokeHandler(
+    requestContext: Context,
+    args: OperationArgs,
+  ): Promise<OperationRetval>;
+
+  describe(): string;
+}
+
+/**
+ * A route with path parameters resolved
+ */
+export interface ResolvedRoute extends RouteEntry {
+  readonly pathParams: PathParameterValues;
+
+  /**
+   * Server/application wide schemas shared by multiple routes,
+   * e.g. model schemas. This is a temporary workaround for
+   * missing support for $ref references, see
+   * https://github.com/strongloop/loopback-next/issues/435
+   */
+  readonly schemas: SchemasObject;
+}
+
+export function createResolvedRoute(
+  route: RouteEntry,
+  pathParams: PathParameterValues,
+): ResolvedRoute {
+  return Object.create(route, {
+    pathParams: {
+      writable: false,
+      value: pathParams,
+    },
+    schemas: {
+      value: {},
+    },
+  });
+}

package/src/router/route-sort.ts

@@ -0,0 +1,74 @@
+// Copyright IBM Corp. 2018,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 {parse, Token} from 'path-to-regexp';
+import {RouteEntry} from './route-entry';
+
+/**
+ * Sorting order for http verbs
+ */
+const HTTP_VERBS: {[name: string]: number} = {
+  post: 1,
+  put: 2,
+  patch: 3,
+  get: 4,
+  head: 5,
+  delete: 6,
+  options: 7,
+};
+
+/**
+ * Compare two routes by verb/path for sorting
+ * @param route1 - First route entry
+ * @param route2 - Second route entry
+ */
+export function compareRoute(
+  route1: Pick<RouteEntry, 'verb' | 'path'>,
+  route2: Pick<RouteEntry, 'verb' | 'path'>,
+): number {
+  // First check the path tokens
+  const path1 = route1.path.replace(/{([^}]*)}(\/|$)/g, ':$1$2');
+  const path2 = route2.path.replace(/{([^}]*)}(\/|$)/g, ':$1$2');
+  const tokensForPath1: Token[] = toTokens(path1);
+  const tokensForPath2: Token[] = toTokens(path2);
+
+  const length =
+    tokensForPath1.length > tokensForPath2.length
+      ? tokensForPath1.length
+      : tokensForPath2.length;
+
+  for (let i = 0; i < length; i++) {
+    const token1 = tokensForPath1[i];
+    const token2 = tokensForPath2[i];
+    if (token1 === token2) continue;
+    if (token1 === undefined) return 1;
+    if (token2 === undefined) return -1;
+    if (token1 < token2) return -1;
+    if (token1 > token2) return 1;
+  }
+  // Then check verb
+  const verb1 = HTTP_VERBS[route1.verb.toLowerCase()] || HTTP_VERBS.get;
+  const verb2 = HTTP_VERBS[route2.verb.toLowerCase()] || HTTP_VERBS.get;
+  if (verb1 !== verb2) return verb1 - verb2;
+  return 0;
+}
+
+/**
+ *
+ * @param path - Parse a path template into tokens
+ */
+function toTokens(path: string) {
+  const tokens: Token[] = [];
+  parse(path).forEach(p => {
+    if (typeof p === 'string') {
+      // The string can be /orders/count
+      tokens.push(...p.split('/').filter(Boolean));
+    } else {
+      // Use `{}` for wildcard as they are larger than any other ascii chars
+      tokens.push(`{}`);
+    }
+  });
+  return tokens;
+}

package/src/router/router-base.ts

@@ -0,0 +1,124 @@
+// 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 {Request} from '../types';
+import {getPathVariables} from './openapi-path';
+import {createResolvedRoute, ResolvedRoute, RouteEntry} from './route-entry';
+import {compareRoute} from './route-sort';
+import {RestRouter, RestRouterOptions} from './rest-router';
+
+/**
+ * Base router implementation that only handles path without variables
+ */
+export abstract class BaseRouter implements RestRouter {
+  /**
+   * A map to optimize matching for routes without variables in the path
+   */
+  protected routesWithoutPathVars: {[key: string]: RouteEntry} = {};
+
+  constructor(protected options: RestRouterOptions = {strict: false}) {}
+
+  protected getKeyForRoute(route: RouteEntry) {
+    return this.getKey(route.verb, route.path);
+  }
+
+  add(route: RouteEntry) {
+    if (!getPathVariables(route.path)) {
+      const key = this.getKeyForRoute(route);
+      this.routesWithoutPathVars[key] = route;
+    } else {
+      this.addRouteWithPathVars(route);
+    }
+  }
+
+  protected getKeyForRequest(request: Request) {
+    return this.getKey(request.method, request.path);
+  }
+
+  find(request: Request) {
+    if (this.options.strict) {
+      return this.findRoute(request.method, request.path);
+    }
+    // Non-strict mode
+    let path = request.path;
+    // First try the exact match
+    const route = this.findRoute(request.method, path);
+    if (route || path === '/') return route;
+    if (path.endsWith('/')) {
+      // Fall back to the path without trailing slash
+      path = path.substring(0, path.length - 1);
+    } else {
+      // Fall back to the path with trailing slash
+      path = path + '/';
+    }
+    return this.findRoute(request.method, path);
+  }
+
+  private findRoute(verb: string, path: string) {
+    const key = this.getKey(verb, path);
+    const route = this.routesWithoutPathVars[key];
+    if (route) return createResolvedRoute(route, {});
+    else return this.findRouteWithPathVars(verb, path);
+  }
+
+  list() {
+    let routes = Object.values(this.routesWithoutPathVars);
+    routes = routes.concat(this.listRoutesWithPathVars());
+    // Sort the routes so that they show up in OpenAPI spec in order
+    return routes.sort(compareRoute);
+  }
+
+  /**
+   * Build a key for verb+path as `/<verb>/<path>`
+   * @param verb - HTTP verb/method
+   * @param path - URL path
+   */
+  protected getKey(verb: string, path: string) {
+    verb = normalizeVerb(verb);
+    path = normalizePath(path);
+    return `/${verb}${path}`;
+  }
+
+  // The following abstract methods need to be implemented by its subclasses
+  /**
+   * Add a route with path variables
+   * @param route - Route
+   */
+  protected abstract addRouteWithPathVars(route: RouteEntry): void;
+
+  /**
+   * Find a route with path variables for a given request
+   * @param request - Http request
+   */
+  protected abstract findRouteWithPathVars(
+    verb: string,
+    path: string,
+  ): ResolvedRoute | undefined;
+
+  /**
+   * List routes with path variables
+   */
+  protected abstract listRoutesWithPathVars(): RouteEntry[];
+}
+
+/**
+ * Normalize http verb to lowercase
+ * @param verb - Http verb
+ */
+function normalizeVerb(verb: string) {
+  // Use lower case, default to `get`
+  return verb?.toLowerCase() || 'get';
+}
+
+/**
+ * Normalize path to make sure it starts with `/`
+ * @param path - Path
+ */
+function normalizePath(path: string) {
+  // Prepend `/` if needed
+  path = path || '/';
+  path = path.startsWith('/') ? path : `/${path}`;
+  return path;
+}

package/src/router/router-spec.ts

@@ -0,0 +1,36 @@
+// Copyright IBM Corp. 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 {OpenApiSpec} from '@loopback/openapi-v3';
+
+export type RouterSpec = Pick<OpenApiSpec, 'paths' | 'components' | 'tags'>;
+
+export function assignRouterSpec(target: RouterSpec, additions: RouterSpec) {
+  if (additions.components) {
+    if (!target.components) target.components = {};
+    for (const key in additions.components) {
+      if (!target.components[key]) target.components[key] = {};
+      Object.assign(target.components[key], additions.components[key]);
+    }
+  }
+
+  for (const url in additions.paths) {
+    if (!(url in target.paths)) target.paths[url] = {};
+    for (const verbOrKey in additions.paths[url]) {
+      // routes registered earlier takes precedence
+      if (verbOrKey in target.paths[url]) continue;
+      target.paths[url][verbOrKey] = additions.paths[url][verbOrKey];
+    }
+  }
+
+  if (additions.tags && additions.tags.length > 0) {
+    if (!target.tags) target.tags = [];
+    for (const tag of additions.tags) {
+      // tags defined earlier take precedence
+      if (target.tags.some(t => t.name === tag.name)) continue;
+      target.tags.push(tag);
+    }
+  }
+}