@loopback/rest 5.2.0 → 6.2.0

package/src/rest.server.ts

@@ -12,6 +12,7 @@ import {
   ContextObserver,
   CoreBindings,
   createBindingFromClass,
+  extensionFor,
   filterByKey,
   filterByTag,
   inject,
@@ -61,7 +62,13 @@ import {
   RoutingTable,
 } from './router';
 import {assignRouterSpec} from './router/router-spec';
-import {DefaultSequence, SequenceFunction, SequenceHandler} from './sequence';
+import {
+  DefaultSequence,
+  MiddlewareSequence,
+  RestMiddlewareGroups,
+  SequenceFunction,
+  SequenceHandler,
+} from './sequence';
 import {Request, RequestBodyParserOptions, Response} from './types';
 
 const debug = debugFactory('loopback:rest:server');
@@ -104,7 +111,8 @@ const SequenceActions = RestBindings.SequenceActions;
  * const server = await app.get('servers.foo');
  * ```
  */
-export class RestServer extends BaseMiddlewareRegistry
+export class RestServer
+  extends BaseMiddlewareRegistry
   implements Server, HttpServerLike {
   /**
    * Handle incoming HTTP(S) request by invoking the corresponding
@@ -163,6 +171,10 @@ export class RestServer extends BaseMiddlewareRegistry
     return this._httpServer ? this._httpServer.listening : false;
   }
 
+  get httpServer(): HttpServer | undefined {
+    return this._httpServer;
+  }
+
   /**
    * The base url for the server, including the basePath if set. For example,
    * the value will be 'http://localhost:3000/api' if `basePath` is set to
@@ -216,6 +228,8 @@ export class RestServer extends BaseMiddlewareRegistry
 
     if (config.sequence) {
       this.sequence(config.sequence);
+    } else {
+      this.sequence(MiddlewareSequence);
     }
 
     if (config.router) {
@@ -249,8 +263,13 @@ export class RestServer extends BaseMiddlewareRegistry
     this.expressMiddleware(cors, this.config.cors, {
       injectConfiguration: false,
       key: 'middleware.cors',
-      group: 'cors',
-    });
+      group: RestMiddlewareGroups.CORS,
+    }).apply(
+      extensionFor(
+        RestTags.REST_MIDDLEWARE_CHAIN,
+        RestTags.ACTION_MIDDLEWARE_CHAIN,
+      ),
+    );
 
     // Set up endpoints for OpenAPI spec/ui
     this._setupOpenApiSpecEndpoints();
@@ -323,8 +342,14 @@ export class RestServer extends BaseMiddlewareRegistry
       this._redirectToSwaggerUI(req, res, next),
     );
     this.expressMiddleware('middleware.apiSpec.defaults', router, {
-      group: 'apiSpec',
-    });
+      group: RestMiddlewareGroups.API_SPEC,
+      upstreamGroups: RestMiddlewareGroups.CORS,
+    }).apply(
+      extensionFor(
+        RestTags.REST_MIDDLEWARE_CHAIN,
+        RestTags.ACTION_MIDDLEWARE_CHAIN,
+      ),
+    );
   }
 
   /**
@@ -445,6 +470,9 @@ export class RestServer extends BaseMiddlewareRegistry
 
     // TODO(bajtos) should we support API spec defined asynchronously?
     const spec: OpenApiSpec = this.getSync(RestBindings.API_SPEC);
+    if (spec.components) {
+      this._httpHandler.registerApiComponents(spec.components);
+    }
     for (const path in spec.paths) {
       for (const verb in spec.paths[path]) {
         const routeSpec: OperationObject = spec.paths[path][verb];
@@ -797,11 +825,13 @@ export class RestServer extends BaseMiddlewareRegistry
    */
   async getApiSpec(requestContext?: RequestContext): Promise<OpenApiSpec> {
     let spec = await this.get<OpenApiSpec>(RestBindings.API_SPEC);
+    spec = cloneDeep(spec);
     const components = this.httpHandler.getApiComponents();
 
     // Apply deep clone to prevent getApiSpec() callers from
     // accidentally modifying our internal routing data
-    spec.paths = cloneDeep(this.httpHandler.describeApiPaths());
+    const paths = cloneDeep(this.httpHandler.describeApiPaths());
+    spec.paths = {...paths, ...spec.paths};
     if (components) {
       const defs = cloneDeep(components);
       spec.components = {...spec.components, ...defs};
@@ -867,10 +897,14 @@ export class RestServer extends BaseMiddlewareRegistry
    * }
    * ```
    *
-   * @param value - The sequence to invoke for each incoming request.
+   * @param sequenceClass - The sequence class to invoke for each incoming request.
    */
-  public sequence(value: Constructor<SequenceHandler>) {
-    this.bind(RestBindings.SEQUENCE).toClass(value);
+  public sequence(sequenceClass: Constructor<SequenceHandler>) {
+    const sequenceBinding = createBindingFromClass(sequenceClass, {
+      key: RestBindings.SEQUENCE,
+    });
+    this.add(sequenceBinding);
+    return sequenceBinding;
   }
 
   /**
@@ -949,10 +983,7 @@ export class RestServer extends BaseMiddlewareRegistry
       return;
     }
 
-    const serverOptions = {};
-    if (protocol === 'https') Object.assign(serverOptions, httpsOptions);
-    Object.assign(serverOptions, {port, host, protocol, path});
-
+    const serverOptions = {...httpsOptions, port, host, protocol, path};
     this._httpServer = new HttpServer(this.requestHandler, serverOptions);
 
     await this._httpServer.start();
@@ -1067,12 +1098,15 @@ const OPENAPI_SPEC_MAPPING: {[key: string]: OpenApiSpecForm} = {
 export interface OpenApiSpecOptions {
   /**
    * Mapping of urls to spec forms, by default:
-   * ```
+   * <br>
    * {
+   *   <br>
    *   '/openapi.json': {version: '3.0.0', format: 'json'},
+   *   <br>
    *   '/openapi.yaml': {version: '3.0.0', format: 'yaml'},
+   *   <br>
    * }
-   * ```
+   *
    */
   endpointMapping?: {[key: string]: OpenApiSpecForm};
 

package/src/router/base-route.ts

@@ -36,11 +36,11 @@ export abstract class BaseRoute implements RouteEntry {
   ): Promise<OperationRetval>;
 
   describe(): string {
-    return `"${this.verb} ${this.path}"`;
+    return `${this.verb} ${this.path}`;
   }
 
   toString() {
-    return `${this.constructor.name} - ${this.verb} ${this.path}`;
+    return `${this.constructor.name} - ${this.describe()}`;
   }
 }
 
@@ -48,6 +48,6 @@ export class RouteSource implements InvocationSource<RouteEntry> {
   type = 'route';
   constructor(readonly value: RouteEntry) {}
   toString() {
-    return `${this.value.verb} ${this.value.path}`;
+    return this.value.toString();
   }
 }

package/src/router/controller-route.ts

@@ -101,7 +101,7 @@ export class ControllerRoute<T> extends BaseRoute {
   }
 
   describe(): string {
-    return `${this._controllerName}.${this._methodName}`;
+    return `${super.describe()} => ${this._controllerName}.${this._methodName}`;
   }
 
   updateBindings(requestContext: Context) {

package/src/router/handler-route.ts

@@ -20,7 +20,9 @@ export class Route extends BaseRoute {
   }
 
   describe(): string {
-    return this._handler.name || super.describe();
+    return `${super.describe()} => ${
+      this._handler.name || this._handler.toString()
+    }`;
   }
 
   updateBindings(requestContext: Context) {

package/src/router/redirect-route.ts

@@ -42,7 +42,7 @@ export class RedirectRoute implements RouteEntry, ResolvedRoute {
   }
 
   describe(): string {
-    return `RedirectRoute from "${this.sourcePath}" to "${this.targetLocation}"`;
+    return `Redirect: "${this.sourcePath}" => "${this.targetLocation}"`;
   }
 
   /**

package/src/sequence.ts

@@ -3,12 +3,25 @@
 // This file is licensed under the MIT License.
 // License text available at https://opensource.org/licenses/MIT
 
-const debug = require('debug')('loopback:rest:sequence');
-import {inject, ValueOrPromise} from '@loopback/core';
-import {InvokeMiddleware} from '@loopback/express';
-import {RestBindings} from './keys';
+import {
+  bind,
+  BindingScope,
+  config,
+  Context,
+  inject,
+  ValueOrPromise,
+} from '@loopback/core';
+import {
+  InvokeMiddleware,
+  InvokeMiddlewareOptions,
+  MiddlewareGroups,
+  MiddlewareView,
+} from '@loopback/express';
+import debugFactory from 'debug';
+import {RestBindings, RestTags} from './keys';
 import {RequestContext} from './request-context';
 import {FindRoute, InvokeMethod, ParseParams, Reject, Send} from './types';
+const debug = debugFactory('loopback:rest:sequence');
 
 const SequenceActions = RestBindings.SequenceActions;
 
@@ -121,3 +134,160 @@ export class DefaultSequence implements SequenceHandler {
     }
   }
 }
+
+/**
+ * Built-in middleware groups for the REST sequence
+ */
+export namespace RestMiddlewareGroups {
+  /**
+   * Invoke downstream middleware to get the result or catch errors so that it
+   * can produce the http response
+   */
+  export const SEND_RESPONSE = 'sendResponse';
+
+  /**
+   * Enforce CORS
+   */
+  export const CORS = MiddlewareGroups.CORS;
+
+  /**
+   * Server OpenAPI specs
+   */
+  export const API_SPEC = MiddlewareGroups.API_SPEC;
+
+  /**
+   * Default middleware group
+   */
+  export const MIDDLEWARE = MiddlewareGroups.MIDDLEWARE;
+  export const DEFAULT = MIDDLEWARE;
+
+  /**
+   * Find the route that can serve the request
+   */
+  export const FIND_ROUTE = 'findRoute';
+
+  /**
+   * Perform authentication
+   */
+  export const AUTHENTICATION = 'authentication';
+
+  /**
+   * Parse the http request to extract parameter values for the operation
+   */
+  export const PARSE_PARAMS = 'parseParams';
+
+  /**
+   * Invoke the target controller method or handler function
+   */
+  export const INVOKE_METHOD = 'invokeMethod';
+}
+
+/**
+ * A sequence implementation using middleware chains
+ */
+@bind({scope: BindingScope.SINGLETON})
+export class MiddlewareSequence implements SequenceHandler {
+  private middlewareView: MiddlewareView;
+
+  static defaultOptions: InvokeMiddlewareOptions = {
+    chain: RestTags.REST_MIDDLEWARE_CHAIN,
+    orderedGroups: [
+      // Please note that middleware is cascading. The `sendResponse` is
+      // added first to invoke downstream middleware to get the result or
+      // catch errors so that it can produce the http response.
+      RestMiddlewareGroups.SEND_RESPONSE,
+
+      RestMiddlewareGroups.CORS,
+      RestMiddlewareGroups.API_SPEC,
+      RestMiddlewareGroups.MIDDLEWARE,
+
+      RestMiddlewareGroups.FIND_ROUTE,
+
+      // authentication depends on the route
+      RestMiddlewareGroups.AUTHENTICATION,
+
+      RestMiddlewareGroups.PARSE_PARAMS,
+
+      RestMiddlewareGroups.INVOKE_METHOD,
+    ],
+
+    /**
+     * Reports an error if there are middleware groups are unreachable as they
+     * are ordered after the `invokeMethod` group.
+     */
+    validate: groups => {
+      const index = groups.indexOf(RestMiddlewareGroups.INVOKE_METHOD);
+      if (index !== -1) {
+        const unreachableGroups = groups.slice(index + 1);
+        if (unreachableGroups.length > 0) {
+          throw new Error(
+            `Middleware groups "${unreachableGroups.join(
+              ',',
+            )}" are not invoked as they are ordered after "${
+              RestMiddlewareGroups.INVOKE_METHOD
+            }"`,
+          );
+        }
+      }
+    },
+  };
+
+  /**
+   * Constructor: Injects `InvokeMiddleware` and `InvokeMiddlewareOptions`
+   *
+   * @param invokeMiddleware - invoker for registered middleware in a chain.
+   * To be injected via RestBindings.INVOKE_MIDDLEWARE_SERVICE.
+   */
+  constructor(
+    @inject.context()
+    context: Context,
+
+    @inject(RestBindings.INVOKE_MIDDLEWARE_SERVICE)
+    readonly invokeMiddleware: InvokeMiddleware,
+    @config()
+    readonly options: InvokeMiddlewareOptions = MiddlewareSequence.defaultOptions,
+  ) {
+    this.middlewareView = new MiddlewareView(context, options);
+    debug('Discovered middleware', this.middlewareView.middlewareBindingKeys);
+  }
+
+  /**
+   * Runs the default sequence. Given a handler context (request and response),
+   * running the sequence will produce a response or an error.
+   *
+   * Default sequence executes these groups of middleware:
+   *
+   *  - `cors`: Enforces `CORS`
+   *  - `openApiSpec`: Serves OpenAPI specs
+   *  - `findRoute`: Finds the appropriate controller method, swagger spec and
+   *    args for invocation
+   *  - `parseParams`: Parses HTTP request to get API argument list
+   *  - `invokeMethod`: Invokes the API which is defined in the Application
+   *    controller method
+   *
+   * In front of the groups above, we have a special middleware called
+   * `sendResponse`, which first invokes downstream middleware to get a result
+   * and handles the result or error respectively.
+   *
+   *  - Writes the result from API into the HTTP response (if the HTTP response
+   *    has not been produced yet by the middleware chain.
+   *  - Catches error logs it using 'logError' if any of the above steps
+   *    in the sequence fails with an error.
+   *
+   * @param context - The request context: HTTP request and response objects,
+   * per-request IoC container and more.
+   */
+  async handle(context: RequestContext): Promise<void> {
+    debug(
+      'Invoking middleware chain %s with groups %s',
+      this.options.chain,
+      this.options.orderedGroups,
+    );
+    const options: InvokeMiddlewareOptions = {
+      middlewareList: this.middlewareView.middlewareBindingKeys,
+      validate: MiddlewareSequence.defaultOptions.validate,
+      ...this.options,
+    };
+    await this.invokeMiddleware(context, options);
+  }
+}

package/src/types.ts

@@ -26,7 +26,7 @@ export * from '@loopback/express';
 export type FindRoute = (request: Request) => ResolvedRoute;
 
 /**
- *
+ * A function to parse OpenAPI operation parameters for a given route
  */
 export type ParseParams = (
   request: Request,
@@ -111,18 +111,23 @@ export type AjvFormat = FormatDefinition & {name: string};
 /**
  * Options for any value validation using AJV
  */
-export interface ValueValidationOptions extends RequestBodyValidationOptions {
+export interface ValueValidationOptions extends ValidationOptions {
   /**
    * Where the data comes from. It can be 'body', 'path', 'header',
    * 'query', 'cookie', etc...
    */
   source?: string;
+
+  /**
+   * Parameter name, as provided in `ParameterObject#name` property.
+   */
+  name?: string;
 }
 
 /**
  * Options for request body validation using AJV
  */
-export interface RequestBodyValidationOptions extends ajv.Options {
+export interface ValidationOptions extends ajv.Options {
   /**
    * Custom cache for compiled schemas by AJV. This setting makes it possible
    * to skip the default cache.
@@ -184,7 +189,7 @@ export interface RequestBodyParserOptions extends Options {
    * This setting is global for all request body parsers and it cannot be
    * overridden inside parser specific properties such as `json` or `text`.
    */
-  validation?: RequestBodyValidationOptions;
+  validation?: ValidationOptions;
   /**
    * Common options for all parsers
    */
@@ -225,3 +230,7 @@ export interface Session {
 export interface RequestWithSession extends Request {
   session: Session;
 }
+
+// For backwards compatibility
+// TODO(SEMVER-MAJOR)
+export type RequestBodyValidationOptions = ValidationOptions;

package/src/validation/ajv-factory.provider.ts

@@ -13,17 +13,19 @@ import {
 import AjvCtor from 'ajv';
 import debugModule from 'debug';
 import {RestBindings, RestTags} from '../keys';
-import {
-  AjvFactory,
-  AjvFormat,
-  AjvKeyword,
-  RequestBodyValidationOptions,
-} from '../types';
+import {AjvFactory, AjvFormat, AjvKeyword, ValidationOptions} from '../types';
+
 const debug = debugModule('loopback:rest:ajv');
 
 const ajvKeywords = require('ajv-keywords');
 const ajvErrors = require('ajv-errors');
 
+export const DEFAULT_AJV_VALIDATION_OPTIONS: ValidationOptions = {
+  $data: true,
+  ajvKeywords: true,
+  ajvErrors: true,
+};
+
 /**
  * A provider class that instantiate an AJV instance
  */
@@ -34,7 +36,7 @@ export class AjvFactoryProvider implements Provider<AjvFactory> {
       RestBindings.REQUEST_BODY_PARSER_OPTIONS.deepProperty('validation'),
       {optional: true},
     )
-    private options: RequestBodyValidationOptions = {},
+    private options: ValidationOptions = DEFAULT_AJV_VALIDATION_OPTIONS,
   ) {}
 
   @inject(filterByTag(RestTags.AJV_KEYWORD))
@@ -45,7 +47,7 @@ export class AjvFactoryProvider implements Provider<AjvFactory> {
 
   value(): AjvFactory {
     return options => {
-      let validationOptions: RequestBodyValidationOptions = {
+      let validationOptions: ValidationOptions = {
         ...this.options,
         ...options,
       };

package/src/validation/request-body.validator.ts

@@ -12,15 +12,17 @@ import {
 } from '@loopback/openapi-v3';
 import ajv, {Ajv} from 'ajv';
 import debugModule from 'debug';
-import _ from 'lodash';
 import util from 'util';
 import {HttpErrors, RequestBody, RestHttpErrors} from '..';
 import {
-  RequestBodyValidationOptions,
   SchemaValidatorCache,
+  ValidationOptions,
   ValueValidationOptions,
 } from '../types';
-import {AjvFactoryProvider} from './ajv-factory.provider';
+import {
+  AjvFactoryProvider,
+  DEFAULT_AJV_VALIDATION_OPTIONS,
+} from './ajv-factory.provider';
 
 const toJsonSchema = require('@openapi-contrib/openapi-schema-to-json-schema');
 const debug = debugModule('loopback:rest:validation');
@@ -39,7 +41,7 @@ export async function validateRequestBody(
   body: RequestBody,
   requestBodySpec?: RequestBodyObject,
   globalSchemas: SchemasObject = {},
-  options: RequestBodyValidationOptions = {},
+  options: ValidationOptions = DEFAULT_AJV_VALIDATION_OPTIONS,
 ) {
   const required = requestBodySpec?.required;
 
@@ -102,12 +104,12 @@ const DEFAULT_COMPILED_SCHEMA_CACHE: SchemaValidatorCache = new WeakMap();
  * Build a cache key for AJV options
  * @param options - Request body validation options
  */
-function getKeyForOptions(options: RequestBodyValidationOptions) {
+function getKeyForOptions(
+  options: ValidationOptions = DEFAULT_AJV_VALIDATION_OPTIONS,
+) {
   const ajvOptions: Record<string, unknown> = {};
   // Sort keys for options
-  const keys = Object.keys(
-    options,
-  ).sort() as (keyof RequestBodyValidationOptions)[];
+  const keys = Object.keys(options).sort() as (keyof ValidationOptions)[];
   for (const k of keys) {
     if (k === 'compiledSchemaCache') continue;
     ajvOptions[k] = options[k];
@@ -177,30 +179,32 @@ export async function validateValueAgainstSchema(
 
   // Throw invalid request body error
   if (options.source === 'body') {
-    const error = RestHttpErrors.invalidRequestBody();
-    addErrorDetails(error, validationErrors);
+    const error = RestHttpErrors.invalidRequestBody(
+      buildErrorDetails(validationErrors),
+    );
     throw error;
   }
 
   // Throw invalid value error
-  const error = new HttpErrors.BadRequest('Invalid value.');
-  addErrorDetails(error, validationErrors);
+  const error = RestHttpErrors.invalidData(value, options.name ?? '(unknown)', {
+    details: buildErrorDetails(validationErrors),
+  });
   throw error;
 }
 
-function addErrorDetails(
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  error: any,
+function buildErrorDetails(
   validationErrors: ajv.ErrorObject[],
-) {
-  error.details = _.map(validationErrors, e => {
-    return {
-      path: e.dataPath,
-      code: e.keyword,
-      message: e.message,
-      info: e.params,
-    };
-  });
+): RestHttpErrors.ValidationErrorDetails[] {
+  return validationErrors.map(
+    (e: ajv.ErrorObject): RestHttpErrors.ValidationErrorDetails => {
+      return {
+        path: e.dataPath,
+        code: e.keyword,
+        message: e.message ?? `must pass validation rule ${e.keyword}`,
+        info: e.params,
+      };
+    },
+  );
 }
 
 /**