@loopback/rest 4.0.0-alpha.8 → 5.0.1

package/src/router/base-route.ts

@@ -0,0 +1,53 @@
+// 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, InvocationSource} from '@loopback/context';
+import {OperationObject} from '@loopback/openapi-v3';
+import {OperationArgs, OperationRetval} from '../types';
+import {RouteEntry} from './route-entry';
+
+/**
+ * Base implementation of RouteEntry
+ */
+export abstract class BaseRoute implements RouteEntry {
+  public readonly verb: string;
+
+  /**
+   * Construct a new route
+   * @param verb - http verb
+   * @param path - http request path pattern
+   * @param spec - OpenAPI operation spec
+   */
+  constructor(
+    verb: string,
+    public readonly path: string,
+    public readonly spec: OperationObject,
+  ) {
+    this.verb = verb.toLowerCase();
+  }
+
+  abstract updateBindings(requestContext: Context): void;
+
+  abstract invokeHandler(
+    requestContext: Context,
+    args: OperationArgs,
+  ): Promise<OperationRetval>;
+
+  describe(): string {
+    return `"${this.verb} ${this.path}"`;
+  }
+
+  toString() {
+    return `${this.constructor.name} - ${this.verb} ${this.path}`;
+  }
+}
+
+export class RouteSource implements InvocationSource<RouteEntry> {
+  type = 'route';
+  constructor(readonly value: RouteEntry) {}
+  toString() {
+    return `${this.value.verb} ${this.value.path}`;
+  }
+}

package/src/router/controller-route.ts

@@ -0,0 +1,241 @@
+// 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 {
+  BindingScope,
+  Constructor,
+  Context,
+  instantiateClass,
+  invokeMethod,
+  ValueOrPromise,
+} from '@loopback/context';
+import {CoreBindings} from '@loopback/core';
+import {ControllerSpec, OperationObject} from '@loopback/openapi-v3';
+import assert from 'assert';
+import debugFactory from 'debug';
+import HttpErrors from 'http-errors';
+import {inspect} from 'util';
+import {RestBindings} from '../keys';
+import {OperationArgs, OperationRetval} from '../types';
+import {BaseRoute, RouteSource} from './base-route';
+
+const debug = debugFactory('loopback:rest:controller-route');
+/*
+ * A controller instance with open properties/methods
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type ControllerInstance = {[name: string]: any} & object;
+
+/**
+ * A factory function to create controller instances synchronously or
+ * asynchronously
+ */
+export type ControllerFactory<T extends ControllerInstance> = (
+  ctx: Context,
+) => ValueOrPromise<T>;
+
+/**
+ * Controller class
+ */
+export type ControllerClass<T extends ControllerInstance> = Constructor<T>;
+
+/**
+ * A route backed by a controller
+ */
+export class ControllerRoute<T> extends BaseRoute {
+  protected readonly _controllerCtor: ControllerClass<T>;
+  protected readonly _controllerName: string;
+  protected readonly _methodName: string;
+  protected readonly _controllerFactory: ControllerFactory<T>;
+
+  /**
+   * Construct a controller based route
+   * @param verb - http verb
+   * @param path - http request path
+   * @param spec - OpenAPI operation spec
+   * @param controllerCtor - Controller class
+   * @param controllerFactory - A factory function to create a controller instance
+   * @param methodName - Controller method name, default to `x-operation-name`
+   */
+  constructor(
+    verb: string,
+    path: string,
+    spec: OperationObject,
+    controllerCtor: ControllerClass<T>,
+    controllerFactory?: ControllerFactory<T>,
+    methodName?: string,
+  ) {
+    const controllerName = spec['x-controller-name'] || controllerCtor.name;
+    methodName = methodName ?? 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: ${controllerName}.`,
+      );
+    }
+
+    super(
+      verb,
+      path,
+      // Add x-controller-name and x-operation-name if not present
+      Object.assign(
+        {
+          'x-controller-name': controllerName,
+          'x-operation-name': methodName,
+          tags: [controllerName],
+        },
+        spec,
+      ),
+    );
+
+    this._controllerFactory =
+      controllerFactory ?? createControllerFactoryForClass(controllerCtor);
+    this._controllerCtor = controllerCtor;
+    this._controllerName = controllerName || controllerCtor.name;
+    this._methodName = methodName;
+  }
+
+  describe(): string {
+    return `${this._controllerName}.${this._methodName}`;
+  }
+
+  updateBindings(requestContext: Context) {
+    /*
+     * Bind current controller to the request context in `SINGLETON` scope.
+     * Within the same request, we always get the same instance of the
+     * current controller when `requestContext.get(CoreBindings.CONTROLLER_CURRENT)`
+     * is invoked.
+     *
+     * Please note the controller class itself can be bound to other scopes,
+     * such as SINGLETON or TRANSIENT (default) in the application or server
+     * context.
+     *
+     * - SINGLETON: all requests share the same instance of a given controller
+     * - TRANSIENT: each request has its own instance of a given controller
+     */
+    requestContext
+      .bind(CoreBindings.CONTROLLER_CURRENT)
+      .toDynamicValue(() => this._controllerFactory(requestContext))
+      .inScope(BindingScope.SINGLETON);
+    requestContext.bind(CoreBindings.CONTROLLER_CLASS).to(this._controllerCtor);
+    requestContext
+      .bind(CoreBindings.CONTROLLER_METHOD_NAME)
+      .to(this._methodName);
+    requestContext.bind(RestBindings.OPERATION_SPEC_CURRENT).to(this.spec);
+  }
+
+  async invokeHandler(
+    requestContext: Context,
+    args: OperationArgs,
+  ): Promise<OperationRetval> {
+    const controller = await requestContext.get<ControllerInstance>(
+      'controller.current',
+    );
+    if (typeof controller[this._methodName] !== 'function') {
+      throw new HttpErrors.NotFound(
+        `Controller method not found: ${this.describe()}`,
+      );
+    }
+    // Invoke the method with dependency injection
+    return invokeMethod(controller, this._methodName, requestContext, args, {
+      source: new RouteSource(this),
+    });
+  }
+}
+
+/**
+ * Create a controller factory function for a given binding key
+ * @param key - Binding key
+ */
+export function createControllerFactoryForBinding<T>(
+  key: string,
+): ControllerFactory<T> {
+  return ctx => ctx.get<T>(key);
+}
+
+/**
+ * Create a controller factory function for a given class
+ * @param controllerCtor - Controller class
+ */
+export function createControllerFactoryForClass<T>(
+  controllerCtor: ControllerClass<T>,
+): ControllerFactory<T> {
+  return async ctx => {
+    // By default, we get an instance of the controller from the context
+    // using `controllers.<controllerName>` as the key
+    let inst = await ctx.get<T>(`controllers.${controllerCtor.name}`, {
+      optional: true,
+    });
+    if (inst === undefined) {
+      inst = await instantiateClass<T>(controllerCtor, ctx);
+    }
+    return inst;
+  };
+}
+
+/**
+ * Create a controller factory function for a given instance
+ * @param controllerCtor - Controller instance
+ */
+export function createControllerFactoryForInstance<T>(
+  controllerInst: T,
+): ControllerFactory<T> {
+  return ctx => controllerInst;
+}
+
+/**
+ * Create routes for a controller with the given spec
+ * @param spec - Controller spec
+ * @param controllerCtor - Controller class
+ * @param controllerFactory - Controller factory
+ */
+export function createRoutesForController<T>(
+  spec: ControllerSpec,
+  controllerCtor: ControllerClass<T>,
+  controllerFactory?: ControllerFactory<T>,
+) {
+  const routes: ControllerRoute<T>[] = [];
+  assert(
+    typeof spec === 'object' && !!spec,
+    'API specification must be a non-null object',
+  );
+  if (!spec.paths || !Object.keys(spec.paths).length) {
+    return routes;
+  }
+
+  debug(
+    'Creating route for controller with API %s',
+    inspect(spec, {depth: null}),
+  );
+
+  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 = joinPath(basePath, p);
+      const route = new ControllerRoute(
+        verb,
+        fullPath,
+        opSpec,
+        controllerCtor,
+        controllerFactory,
+      );
+      routes.push(route);
+    }
+  }
+  return routes;
+}
+
+export function 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;
+}

package/src/router/external-express-routes.ts

@@ -0,0 +1,139 @@
+// 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 {Context} from '@loopback/context';
+import {
+  executeExpressRequestHandler,
+  ExpressRequestHandler,
+  Request,
+} from '@loopback/express';
+import {
+  OpenApiSpec,
+  OperationObject,
+  SchemasObject,
+} from '@loopback/openapi-v3';
+import express from 'express';
+import {PathParams} from 'express-serve-static-core';
+import HttpErrors from 'http-errors';
+import {ServeStaticOptions} from 'serve-static';
+import {RequestContext} from '../request-context';
+import {OperationArgs, OperationRetval, PathParameterValues} from '../types';
+import {ResolvedRoute, RouteEntry} from './route-entry';
+import {assignRouterSpec, RouterSpec} from './router-spec';
+
+/**
+ * A registry of external, Express-style routes. These routes are invoked
+ * _after_ no LB4 route (controller or handler based) matched the incoming
+ * request.
+ *
+ * @internal
+ */
+export class ExternalExpressRoutes {
+  protected _externalRoutes: express.Router = express.Router();
+  protected _staticRoutes: express.Router = express.Router();
+  protected _specForExternalRoutes: RouterSpec = {paths: {}};
+
+  get routerSpec(): RouterSpec {
+    return this._specForExternalRoutes;
+  }
+
+  public registerAssets(
+    path: PathParams,
+    rootDir: string,
+    options?: ServeStaticOptions,
+  ) {
+    this._staticRoutes.use(path, express.static(rootDir, options));
+  }
+
+  public mountRouter(
+    basePath: string,
+    router: ExpressRequestHandler,
+    spec: RouterSpec = {paths: {}},
+  ) {
+    this._externalRoutes.use(basePath, router);
+
+    spec = rebaseOpenApiSpec(spec, basePath);
+    assignRouterSpec(this._specForExternalRoutes, spec);
+  }
+
+  find(request: Request): ResolvedRoute {
+    return new ExternalRoute(
+      this._externalRoutes,
+      this._staticRoutes,
+      request.method,
+      request.url,
+      {
+        description: 'External route or a static asset',
+        'x-visibility': 'undocumented',
+        responses: {},
+      },
+    );
+  }
+}
+
+class ExternalRoute implements RouteEntry, ResolvedRoute {
+  // ResolvedRoute API
+  readonly pathParams: PathParameterValues = [];
+  readonly schemas: SchemasObject = {};
+
+  constructor(
+    private readonly _externalRouter: express.Router,
+    private readonly _staticAssets: express.Router,
+    public readonly verb: string,
+    public readonly path: string,
+    public readonly spec: OperationObject,
+  ) {}
+
+  updateBindings(requestContext: Context): void {
+    // no-op
+  }
+
+  async invokeHandler(
+    {request, response}: RequestContext,
+    args: OperationArgs,
+  ): Promise<OperationRetval> {
+    let handled = await executeExpressRequestHandler(
+      this._externalRouter,
+      request,
+      response,
+    );
+    if (handled) return;
+
+    handled = await executeExpressRequestHandler(
+      this._staticAssets,
+      request,
+      response,
+    );
+    if (handled) return;
+
+    // Express router called next, which means no route was matched
+    throw new HttpErrors.NotFound(
+      `Endpoint "${request.method} ${request.path}" not found.`,
+    );
+  }
+
+  describe(): string {
+    // TODO(bajtos) provide better description for Express routes with spec
+    return `External Express route "${this.verb} ${this.path}"`;
+  }
+}
+
+export function rebaseOpenApiSpec<T extends Partial<OpenApiSpec>>(
+  spec: T,
+  basePath: string,
+): T {
+  if (!spec.paths) return spec;
+  if (!basePath || basePath === '/') return spec;
+
+  const localPaths = spec.paths;
+  // Don't modify the spec object provided to us.
+  spec = Object.assign({}, spec);
+  spec.paths = {};
+  for (const url in localPaths) {
+    spec.paths[`${basePath}${url}`] = localPaths[url];
+  }
+
+  return spec;
+}

package/src/router/handler-route.ts

@@ -0,0 +1,44 @@
+// 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, invokeMethodWithInterceptors} from '@loopback/context';
+import {OperationObject} from '@loopback/openapi-v3';
+import {RestBindings} from '../keys';
+import {OperationArgs, OperationRetval} from '../types';
+import {BaseRoute, RouteSource} from './base-route';
+
+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) {
+    requestContext.bind(RestBindings.OPERATION_SPEC_CURRENT).to(this.spec);
+  }
+
+  async invokeHandler(
+    requestContext: Context,
+    args: OperationArgs,
+  ): Promise<OperationRetval> {
+    // Use `invokeMethodWithInterceptors` to invoke the handler function so
+    // that global interceptors are applied
+    return invokeMethodWithInterceptors(
+      requestContext,
+      this,
+      '_handler',
+      args,
+      {source: new RouteSource(this)},
+    );
+  }
+}

package/src/router/index.ts

@@ -0,0 +1,24 @@
+// 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
+
+// routes
+export * from './route-entry';
+export * from './base-route';
+export * from './controller-route';
+export * from './handler-route';
+export * from './external-express-routes';
+export * from './redirect-route';
+
+// routers
+export * from './rest-router';
+export * from './trie-router';
+export * from './regexp-router';
+
+// helpers
+export * from './routing-table';
+export * from './route-sort';
+export * from './openapi-path';
+export * from './trie';
+export * from './router-spec';

package/src/router/openapi-path.ts

@@ -0,0 +1,67 @@
+// 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 {parse} from 'path-to-regexp';
+
+/**
+ * OpenAPI spec 3.x does not specify the valid forms of path templates.
+ *
+ * Other ones such as [URI Template](https://tools.ietf.org/html/rfc6570#section-2.3)
+ * or [path-to-regexp](https://github.com/pillarjs/path-to-regexp#named-parameters)
+ * allows `[A-Za-z0-9_]`
+ */
+const POSSIBLE_VARNAME_PATTERN = /\{([^\}]+)\}/g;
+const VALID_VARNAME_PATTERN = /^[A-Za-z0-9_]+$/;
+
+/**
+ * Validate the path to be compatible with OpenAPI path template. No parameter
+ * modifier, custom pattern, or unnamed parameter is allowed.
+ */
+export function validateApiPath(path = '/') {
+  const tokens = parse(path);
+  for (const token of tokens) {
+    if (typeof token === 'string') continue;
+    if (typeof token === 'object') {
+      const name = token.name;
+      if (typeof name === 'string' && name !== '') {
+        throw new Error(
+          `Invalid path template: '${path}'. Please use {${name}} instead of ':${name}'`,
+        );
+      }
+      if (typeof name === 'number') {
+        throw new Error(`Unnamed parameter is not allowed in path '${path}'`);
+      }
+      const valid = token.prefix.match(VALID_VARNAME_PATTERN);
+      if (!valid) {
+        throw new Error(
+          `Invalid parameter name '${token.prefix}' found in path '${path}'`,
+        );
+      }
+      if (['?', '+', '*'].includes(token.modifier)) {
+        throw new Error(
+          `Parameter modifier '{${token.prefix}}${token.modifier}' is not allowed in path '${path}`,
+        );
+      }
+    }
+  }
+  return path;
+}
+
+/**
+ * Get all path variables. For example, `/root/{foo}/bar` => `['foo']`
+ */
+export function getPathVariables(path: string) {
+  return path.match(POSSIBLE_VARNAME_PATTERN);
+}
+
+/**
+ * Convert an OpenAPI path to Express (path-to-regexp) style
+ * @param path - OpenAPI path with optional variables as `{var}`
+ */
+export function toExpressPath(path: string) {
+  // Convert `.` to `\\.` so that path-to-regexp will treat it as the plain
+  // `.` character
+  return path.replace(POSSIBLE_VARNAME_PATTERN, '{:$1}').replace('.', '\\.');
+}

package/src/router/redirect-route.ts

@@ -0,0 +1,64 @@
+// Copyright IBM Corp. 2019,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 {OperationObject, SchemasObject} from '@loopback/openapi-v3';
+import {ResolvedRoute, RouteEntry} from '.';
+import {RequestContext} from '../request-context';
+import {OperationArgs, OperationRetval, PathParameterValues} from '../types';
+
+export class RedirectRoute implements RouteEntry, ResolvedRoute {
+  // ResolvedRoute API
+  readonly pathParams: PathParameterValues = [];
+  readonly schemas: SchemasObject = {};
+
+  // RouteEntry implementation
+  readonly verb: string = 'get';
+  readonly path: string;
+  readonly spec: OperationObject = {
+    description: 'LoopBack Redirect route',
+    'x-visibility': 'undocumented',
+    responses: {},
+  };
+
+  constructor(
+    public readonly sourcePath: string,
+    public readonly targetLocation: string,
+    public readonly statusCode: number = 303,
+  ) {
+    this.path = sourcePath;
+  }
+
+  async invokeHandler(
+    {response}: RequestContext,
+    args: OperationArgs,
+  ): Promise<OperationRetval> {
+    response.redirect(this.statusCode, this.targetLocation);
+  }
+
+  updateBindings(requestContext: RequestContext) {
+    // no-op
+  }
+
+  describe(): string {
+    return `RedirectRoute from "${this.sourcePath}" to "${this.targetLocation}"`;
+  }
+
+  /**
+   * type guard type checker for this class
+   * @param obj
+   */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  static isRedirectRoute(obj: any): obj is RedirectRoute {
+    const redirectOptions = obj as RedirectRoute;
+    if (
+      redirectOptions?.targetLocation &&
+      redirectOptions.spec &&
+      redirectOptions.spec.description === 'LoopBack Redirect route'
+    ) {
+      return true;
+    }
+    return false;
+  }
+}