@loopback/rest 4.0.0-alpha.8 → 5.0.1

package/src/sequence.ts

@@ -1,20 +1,14 @@
-// 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
 
-const debug = require('debug')('loopback:core:sequence');
-import {ServerResponse} from 'http';
-import {inject, Context} from '@loopback/context';
-import {
-  FindRoute,
-  InvokeMethod,
-  ParsedRequest,
-  Send,
-  Reject,
-  ParseParams,
-} from './internal-types';
+const debug = require('debug')('loopback:rest:sequence');
+import {inject, ValueOrPromise} from '@loopback/context';
+import {InvokeMiddleware} from '@loopback/express';
 import {RestBindings} from './keys';
+import {RequestContext} from './request-context';
+import {FindRoute, InvokeMethod, ParseParams, Reject, Send} from './types';
 
 const SequenceActions = RestBindings.SequenceActions;
 
@@ -23,10 +17,9 @@ const SequenceActions = RestBindings.SequenceActions;
  * sequence of actions to handle an incoming request.
  */
 export type SequenceFunction = (
+  context: RequestContext,
   sequence: DefaultSequence,
-  request: ParsedRequest,
-  response: ServerResponse,
-) => Promise<void> | void;
+) => ValueOrPromise<void>;
 
 /**
  * A sequence handler is a class implementing sequence of actions
@@ -36,15 +29,16 @@ export interface SequenceHandler {
   /**
    * Handle the request by running the configured sequence of actions.
    *
-   * @param request The incoming HTTP request
-   * @param response The HTTP server response where to write the result
+   * @param context - The request context: HTTP request and response objects,
+   * per-request IoC container and more.
    */
-  handle(request: ParsedRequest, response: ServerResponse): Promise<void>;
+  handle(context: RequestContext): Promise<void>;
 }
 
 /**
  * The default implementation of SequenceHandler.
  *
+ * @remarks
  * This class implements default Sequence for the LoopBack framework.
  * Default sequence is used if user hasn't defined their own Sequence
  * for their application.
@@ -53,31 +47,36 @@ export interface SequenceHandler {
  * when the API request comes in. User defines APIs in their Application
  * Controller class.
  *
+ * @example
  * User can bind their own Sequence to app as shown below
  * ```ts
  * app.bind(CoreBindings.SEQUENCE).toClass(MySequence);
  * ```
  */
 export class DefaultSequence implements SequenceHandler {
+  /**
+   * Optional invoker for registered middleware in a chain.
+   * To be injected via SequenceActions.INVOKE_MIDDLEWARE.
+   */
+  @inject(SequenceActions.INVOKE_MIDDLEWARE, {optional: true})
+  protected invokeMiddleware: InvokeMiddleware = () => false;
+
   /**
    * Constructor: Injects findRoute, invokeMethod & logError
    * methods as promises.
    *
-   * @param {Context} ctx The context for the sequence (injected via
-   * RestBindings.Http.CONTEXT).
-   * @param {FindRoute} findRoute Finds the appropriate controller method,
+   * @param findRoute - Finds the appropriate controller method,
    *  spec and args for invocation (injected via SequenceActions.FIND_ROUTE).
-   * @param {ParseParams} parseParams The parameter parsing function (injected
+   * @param parseParams - The parameter parsing function (injected
    * via SequenceActions.PARSE_PARAMS).
-   * @param {InvokeMethod} invoke Invokes the method specified by the route
+   * @param invoke - Invokes the method specified by the route
    * (injected via SequenceActions.INVOKE_METHOD).
-   * @param {Send} send The action to merge the invoke result with the response
+   * @param send - The action to merge the invoke result with the response
    * (injected via SequenceActions.SEND)
-   * @param {Reject} reject The action to take if the invoke returns a rejected
+   * @param reject - The action to take if the invoke returns a rejected
    * promise result (injected via SequenceActions.REJECT).
    */
   constructor(
-    @inject(RestBindings.Http.CONTEXT) public ctx: Context,
     @inject(SequenceActions.FIND_ROUTE) protected findRoute: FindRoute,
     @inject(SequenceActions.PARSE_PARAMS) protected parseParams: ParseParams,
     @inject(SequenceActions.INVOKE_METHOD) protected invoke: InvokeMethod,
@@ -86,10 +85,11 @@ export class DefaultSequence implements SequenceHandler {
   ) {}
 
   /**
-   * Runs the default sequence. Given a request and response, running the
-   * sequence will produce a response or an error.
+   * 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 steps
+   *  - Executes middleware for CORS, OpenAPI spec endpoints
    *  - Finds the appropriate controller method, swagger spec
    *    and args for invocation
    *  - Parses HTTP request to get API argument list
@@ -97,20 +97,27 @@ export class DefaultSequence implements SequenceHandler {
    *  - Writes the result from API into the HTTP response
    *  - Error is caught and logged using 'logError' if any of the above steps
    *    in the sequence fails with an error.
-   * @param req Parsed incoming HTTP request
-   * @param res HTTP server response with result from Application controller
-   *  method invocation
+   *
+   * @param context - The request context: HTTP request and response objects,
+   * per-request IoC container and more.
    */
-  async handle(req: ParsedRequest, res: ServerResponse) {
+  async handle(context: RequestContext): Promise<void> {
     try {
-      const route = this.findRoute(req);
-      const args = await this.parseParams(req, route);
+      const {request, response} = context;
+      // Invoke registered Express middleware
+      const finished = await this.invokeMiddleware(context);
+      if (finished) {
+        // The response been produced by the middleware chain
+        return;
+      }
+      const route = this.findRoute(request);
+      const args = await this.parseParams(request, route);
       const result = await this.invoke(route, args);
 
       debug('%s result -', route.describe(), result);
-      this.send(res, result);
-    } catch (err) {
-      this.reject(res, req, err);
+      this.send(response, result);
+    } catch (error) {
+      this.reject(context, error);
     }
   }
 }

package/src/spec-enhancers/consolidate.spec-enhancer.ts

@@ -0,0 +1,182 @@
+// Copyright IBM Corp. 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 {
+  ApplicationConfig,
+  bind,
+  BindingScope,
+  CoreBindings,
+  inject,
+} from '@loopback/core';
+import {
+  asSpecEnhancer,
+  ISpecificationExtension,
+  isSchemaObject,
+  OASEnhancer,
+  OpenApiSpec,
+  ReferenceObject,
+  SchemaObject,
+} from '@loopback/openapi-v3';
+import debugFactory from 'debug';
+import compare from 'json-schema-compare';
+import _ from 'lodash';
+
+const debug = debugFactory('loopback:openapi:spec-enhancer:consolidate');
+
+/**
+ * This enhancer consolidates schemas into `/components/schemas` and replaces
+ * instances of said schema with a $ref pointer.
+ *
+ * Please note that the title property must be set on a schema in order to be
+ * considered for consolidation.
+ *
+ * For example, with the following schema instance:
+ *
+ * ```json
+ * schema: {
+ *   title: 'loopback.example',
+ *   properties: {
+ *     test: {
+ *       type: 'string',
+ *     },
+ *   },
+ * }
+ * ```
+ *
+ * The consolidator will copy the schema body to
+ * `/components/schemas/loopback.example` and replace any instance of the schema
+ * with a reference to the component schema as follows:
+ *
+ * ```json
+ * schema: {
+ *   $ref: '#/components/schemas/loopback.example',
+ * }
+ * ```
+ *
+ * When comparing schemas to avoid naming collisions, the description field
+ * is ignored.
+ */
+@bind(asSpecEnhancer, {scope: BindingScope.SINGLETON})
+export class ConsolidationEnhancer implements OASEnhancer {
+  name = 'consolidate';
+  disabled: boolean;
+
+  constructor(
+    @inject(CoreBindings.APPLICATION_CONFIG, {optional: true})
+    readonly config?: ApplicationConfig,
+  ) {
+    this.disabled = this.config?.rest?.openApiSpec?.consolidate === false;
+  }
+
+  modifySpec(spec: OpenApiSpec): OpenApiSpec {
+    return !this.disabled ? this.consolidateSchemaObjects(spec) : spec;
+  }
+
+  /**
+   * Recursively search OpenApiSpec PathsObject for SchemaObjects with title
+   * property. Moves reusable schema bodies to #/components/schemas and replace
+   * with json pointer. It handles title collisions with schema body comparision.
+   */
+  private consolidateSchemaObjects(spec: OpenApiSpec): OpenApiSpec {
+    // use 'paths' as crawl root
+    this.recursiveWalk(spec.paths, ['paths'], spec);
+
+    return spec;
+  }
+
+  private recursiveWalk(
+    rootSchema: ISpecificationExtension,
+    parentPath: Array<string>,
+    spec: OpenApiSpec,
+  ) {
+    if (this.isTraversable(rootSchema)) {
+      Object.entries(rootSchema).forEach(([key, subSchema]) => {
+        if (subSchema) {
+          this.recursiveWalk(subSchema, parentPath.concat(key), spec);
+          this.processSchema(subSchema, parentPath.concat(key), spec);
+        }
+      });
+    }
+  }
+
+  /**
+   * Carry out schema consolidation after tree traversal. If 'title' property
+   * set then we consider current schema for consolidation. SchemaObjects with
+   * properties (and title set) are moved to #/components/schemas/<title> and
+   * replaced with ReferenceObject.
+   *
+   * Features:
+   *  - name collision protection
+   *
+   * @param schema - current schema element to process
+   * @param parentPath - path object to parent
+   * @param spec - subject OpenApi specification
+   */
+  private processSchema(
+    schema: SchemaObject | ReferenceObject,
+    parentPath: Array<string>,
+    spec: OpenApiSpec,
+  ) {
+    const schemaObj = this.ifConsolidationCandidate(schema);
+    if (schemaObj) {
+      // name collison protection
+      let instanceNo = 1;
+      let title = schemaObj.title!;
+      let refSchema = this.getRefSchema(title, spec);
+      while (
+        refSchema &&
+        !compare(schemaObj as ISpecificationExtension, refSchema, {
+          ignore: ['description'],
+        })
+      ) {
+        title = `${schemaObj.title}${instanceNo++}`;
+        refSchema = this.getRefSchema(title, spec);
+      }
+      if (!refSchema) {
+        debug('Creating new component $ref with schema %j', schema);
+        this.patchRef(title, schema, spec);
+      }
+      debug('Creating link to $ref %j', title);
+      this.patchPath(title, parentPath, spec);
+    }
+  }
+
+  private getRefSchema(
+    name: string,
+    spec: OpenApiSpec,
+  ): ISpecificationExtension | undefined {
+    const schema = _.get(spec, ['components', 'schemas', name]);
+
+    return schema;
+  }
+
+  private patchRef(
+    name: string,
+    value: ISpecificationExtension,
+    spec: OpenApiSpec,
+  ) {
+    _.set(spec, ['components', 'schemas', name], value);
+  }
+
+  private patchPath(name: string, path: Array<string>, spec: OpenApiSpec) {
+    const patch = {
+      $ref: `#/components/schemas/${name}`,
+    };
+    _.set(spec, path, patch);
+  }
+
+  private ifConsolidationCandidate(
+    schema: SchemaObject | ReferenceObject,
+  ): SchemaObject | undefined {
+    // use title to discriminate references
+    return isSchemaObject(schema) && schema.properties && schema.title
+      ? schema
+      : undefined;
+  }
+
+  private isTraversable(schema: ISpecificationExtension): boolean {
+    return schema && typeof schema === 'object' ? true : false;
+  }
+}

package/src/spec-enhancers/info.spec-enhancer.ts

@@ -0,0 +1,92 @@
+// Copyright IBM Corp. 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 {
+  bind,
+  BindingScope,
+  inject,
+  JSONObject,
+  JSONValue,
+} from '@loopback/context';
+import {ApplicationMetadata, CoreBindings} from '@loopback/core';
+import {
+  asSpecEnhancer,
+  ContactObject,
+  mergeOpenAPISpec,
+  OASEnhancer,
+  OpenApiSpec,
+} from '@loopback/openapi-v3';
+import debugFactory from 'debug';
+
+const debug = debugFactory('loopback:openapi:spec-enhancer:info');
+
+/**
+ * An OpenAPI spec enhancer to populate `info` with application metadata
+ * (package.json).
+ */
+@bind(asSpecEnhancer, {scope: BindingScope.SINGLETON})
+export class InfoSpecEnhancer implements OASEnhancer {
+  name = 'info';
+
+  constructor(
+    @inject(CoreBindings.APPLICATION_METADATA, {optional: true})
+    readonly pkg?: ApplicationMetadata,
+  ) {}
+
+  modifySpec(spec: OpenApiSpec): OpenApiSpec {
+    if (this.pkg == null) {
+      debug('Application metadata is not found. Skipping spec enhancing.');
+      return spec;
+    }
+    const contact: ContactObject = InfoSpecEnhancer.parseAuthor(
+      this.pkg.author,
+    );
+    const patchSpec = {
+      info: {
+        title: this.pkg.name,
+        description: this.pkg.description,
+        version: this.pkg.version,
+        contact,
+      },
+    };
+    debug('Enhancing OpenAPI spec with %j', patchSpec);
+    return mergeOpenAPISpec(spec, patchSpec);
+  }
+
+  /**
+   * Parse package.json
+   * {@link https://docs.npmjs.com/files/package.json#people-fields-author-contributors | author}
+   *
+   * @param author - Author string or object from package.json
+   */
+  private static parseAuthor(author: JSONValue) {
+    let contact: ContactObject = {};
+    if (author == null) {
+      contact = {};
+    } else if (typeof author === 'string') {
+      // "Barney Rubble <b@rubble.com> (http://barnyrubble.tumblr.com/)"
+      const emailRegex = /<([^<>]+)>/; // <email>
+      const urlRegex = /\(([^()]+)\)/; // (url)
+      const nameRegex = /([^<>()]+)/;
+      contact = {
+        name: nameRegex.exec(author)?.[1]?.trim(),
+        email: emailRegex.exec(author)?.[1]?.trim(),
+        url: urlRegex.exec(author)?.[1]?.trim(),
+      };
+    } else if (typeof author === 'object') {
+      const authorObj = author as JSONObject;
+      contact = {
+        name: authorObj.name as string,
+        email: authorObj.email as string,
+        url: authorObj.url as string,
+      };
+    }
+    // Remove undefined/null values
+    for (const p in contact) {
+      if (contact[p] == null) delete contact[p];
+    }
+    return contact;
+  }
+}

package/src/types.ts

@@ -0,0 +1,216 @@
+// 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 {HandlerContext, Request, Response} from '@loopback/express';
+import {ReferenceObject, SchemaObject} from '@loopback/openapi-v3';
+import ajv, {Ajv, FormatDefinition, KeywordDefinition} from 'ajv';
+import {
+  Options,
+  OptionsJson,
+  OptionsText,
+  OptionsUrlencoded,
+} from 'body-parser';
+import {ResolvedRoute, RouteEntry} from './router';
+
+/**
+ * Re-export types from `./middleware`
+ */
+export * from '@loopback/express';
+
+/**
+ * Find a route matching the incoming request.
+ * Throw an error when no route was found.
+ */
+export type FindRoute = (request: Request) => ResolvedRoute;
+
+/**
+ *
+ */
+export type ParseParams = (
+  request: Request,
+  route: ResolvedRoute,
+) => Promise<OperationArgs>;
+
+/**
+ * Invokes a method defined in the Application Controller
+ *
+ * @param controller - Name of end-user's application controller
+ *  class which defines the methods.
+ * @param method - Method name in application controller class
+ * @param args - Operation arguments for the method
+ * @returns OperationRetval Result from method invocation
+ */
+export type InvokeMethod = (
+  route: RouteEntry,
+  args: OperationArgs,
+) => Promise<OperationRetval>;
+
+/**
+ * Send the operation response back to the client.
+ *
+ * @param response - The response the response to send to.
+ * @param result - The operation result to send.
+ */
+export type Send = (response: Response, result: OperationRetval) => void;
+
+/**
+ * Reject the request with an error.
+ *
+ * @param handlerContext - The context object holding HTTP request, response
+ * and other data  needed to handle an incoming HTTP request.
+ * @param err - The error.
+ */
+export type Reject = (handlerContext: HandlerContext, err: Error) => void;
+
+/**
+ * Log information about a failed request.
+ *
+ * @param err - The error reported by request handling code.
+ * @param statusCode - Status code of the HTTP response
+ * @param request - The request that failed.
+ */
+export type LogError = (
+  err: Error,
+  statusCode: number,
+  request: Request,
+) => void;
+
+/**
+ * Cache for AJV schema validators
+ */
+export type SchemaValidatorCache = WeakMap<
+  SchemaObject | ReferenceObject, // First keyed by schema object
+  Map<string, ajv.ValidateFunction> // Second level keyed by stringified AJV options
+>;
+
+/**
+ * Options for AJV errors
+ */
+export type AjvErrorOptions = {
+  keepErrors?: boolean;
+  singleError?: boolean;
+};
+
+/**
+ * Factory function for Ajv instances
+ */
+export type AjvFactory = (options?: ajv.Options) => Ajv;
+
+/**
+ * Ajv keyword definition with a name
+ */
+export type AjvKeyword = KeywordDefinition & {name: string};
+
+/**
+ * Ajv format definition with a name
+ */
+export type AjvFormat = FormatDefinition & {name: string};
+
+/**
+ * Options for request body validation using AJV
+ */
+export interface RequestBodyValidationOptions extends ajv.Options {
+  /**
+   * Custom cache for compiled schemas by AJV. This setting makes it possible
+   * to skip the default cache.
+   */
+  compiledSchemaCache?: SchemaValidatorCache;
+  /**
+   * Enable additional AJV keywords from https://github.com/epoberezkin/ajv-keywords
+   * - `true`: Add all keywords from `ajv-keywords`
+   * - `string[]`: Add an array of keywords from `ajv-keywords`
+   */
+  ajvKeywords?: true | string[];
+  /**
+   * Enable custom error messages in JSON-Schema for AJV validator
+   * from https://github.com/epoberezkin/ajv-errors
+   * - `true`: Enable `ajv-errors`
+   * - `AjvErrorOptions`: Enable `ajv-errors` with options
+   */
+  ajvErrors?: true | AjvErrorOptions;
+  /**
+   * A function that transform the `ErrorObject`s reported by AJV.
+   * This could be used for error messages customization, localization, etc.
+   */
+  ajvErrorTransformer?: (errors: ajv.ErrorObject[]) => ajv.ErrorObject[];
+
+  /**
+   * A factory to create Ajv instance
+   */
+  ajvFactory?: (options: ajv.Options) => Ajv;
+}
+
+/* eslint-disable @typescript-eslint/no-explicit-any */
+
+/**
+ * Options for request body parsing
+ * See https://github.com/expressjs/body-parser/#options
+ *
+ * Built-in parsers retrieve their own options from the request body parser
+ * options. The parser specific properties override common ones.
+ */
+export interface RequestBodyParserOptions extends Options {
+  /**
+   * Options for json parser
+   */
+  json?: OptionsJson;
+  /**
+   * Options for urlencoded parser
+   */
+  urlencoded?: OptionsUrlencoded;
+  /**
+   * Options for text parser
+   */
+  text?: OptionsText;
+  /**
+   * Options for raw parser
+   */
+  raw?: Options;
+  /**
+   * Validation options for AJV, see https://github.com/epoberezkin/ajv#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;
+  /**
+   * Common options for all parsers
+   */
+  [name: string]: unknown;
+}
+
+export type PathParameterValues = {[key: string]: any};
+export type OperationArgs = any[];
+
+/**
+ * Return value of a controller method (a function implementing an operation).
+ * This is a type alias for "any", used to distinguish
+ * operation results from other "any" typed values.
+ */
+export type OperationRetval = any;
+
+/**
+ * user profile to add in session
+ */
+export interface SessionUserProfile {
+  provider: string;
+  token: string;
+  email: string;
+  [attribute: string]: any;
+}
+
+/**
+ * interface to set variables in user session
+ */
+export interface Session {
+  profile: SessionUserProfile;
+  [key: string]: any;
+}
+
+/**
+ * extending express request type with a session field
+ */
+export interface RequestWithSession extends Request {
+  session: Session;
+}