@loopback/rest 4.0.0-alpha.8 → 5.0.1

package/src/coercion/validator.ts

@@ -0,0 +1,98 @@
+// 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 {ParameterObject, SchemaObject} from '@loopback/openapi-v3';
+import {RestHttpErrors} from '../';
+
+/**
+ * A set of options to pass into the validator functions
+ */
+export type ValidationOptions = {
+  required?: boolean;
+};
+
+/**
+ * The context information that a validator needs
+ */
+export type ValidationContext = {
+  parameterSpec: ParameterObject;
+};
+
+/**
+ * Validator class provides a bunch of functions that perform
+ * validations on the request parameters and request body.
+ */
+export class Validator {
+  constructor(public ctx: ValidationContext) {}
+
+  /**
+   * The validation executed before type coercion. Like
+   * checking absence.
+   *
+   * @param type - A parameter's type.
+   * @param value - A parameter's raw value from http request.
+   * @param opts - options
+   */
+  validateParamBeforeCoercion(
+    value: string | object | undefined,
+    opts?: ValidationOptions,
+  ) {
+    if (this.isAbsent(value) && this.isRequired(opts)) {
+      const name = this.ctx.parameterSpec.name;
+      throw RestHttpErrors.missingRequired(name);
+    }
+  }
+
+  /**
+   * Check is a parameter required or not.
+   *
+   * @param opts
+   */
+  isRequired(opts?: ValidationOptions) {
+    if (this.ctx.parameterSpec.required) return true;
+    if (opts?.required) return true;
+    return false;
+  }
+
+  /**
+   * Return `true` if the value is empty, return `false` otherwise.
+   *
+   * @param value
+   */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  isAbsent(value: any) {
+    if (value === '' || value === undefined) return true;
+
+    const spec: ParameterObject = this.ctx.parameterSpec;
+    const schema: SchemaObject = this.ctx.parameterSpec.schema ?? {};
+    const valueIsNull = value === 'null' || value === null;
+
+    if (this.isUrlEncodedJsonParam()) {
+      // is this an url encoded Json object query parameter?
+      // check for NULL values
+      if (valueIsNull) return true;
+    } else if (spec.schema) {
+      // if parameter spec contains schema object, check if supplied value is NULL
+      if (schema.type === 'object' && valueIsNull) return true;
+    }
+
+    return false;
+  }
+
+  /**
+   * Return `true` if defined specification is for a url encoded Json object query parameter
+   *
+   * for url encoded Json object query parameters,
+   * schema is defined under content['application/json']
+   */
+  isUrlEncodedJsonParam() {
+    const spec: ParameterObject = this.ctx.parameterSpec;
+
+    if (spec.in === 'query' && spec.content?.['application/json']?.schema) {
+      return true;
+    }
+    return false;
+  }
+}

package/src/http-handler.ts

@@ -1,74 +1,117 @@
-// Copyright IBM Corp. 2017. All Rights Reserved.
+// Copyright IBM Corp. 2017,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 {PathsObject} from '@loopback/openapi-spec';
-import {ServerRequest, ServerResponse} from 'http';
-import {ControllerSpec} from './router/metadata';
-
-import {SequenceHandler} from './sequence';
 import {
-  RoutingTable,
-  parseRequestUrl,
+  ComponentsObject,
+  ControllerSpec,
+  PathObject,
+  ReferenceObject,
+  SchemaObject,
+  SchemasObject,
+} from '@loopback/openapi-v3';
+import {RestBindings} from './keys';
+import {RequestContext} from './request-context';
+import {RestServerResolvedConfig} from './rest.server';
+import {
+  ControllerClass,
+  ControllerFactory,
   ResolvedRoute,
   RouteEntry,
-  ControllerClass,
-} from './router/routing-table';
-import {ParsedRequest} from './internal-types';
-
-import {RestBindings} from './keys';
+  RoutingTable,
+} from './router';
+import {SequenceHandler} from './sequence';
+import {Request, Response} from './types';
 
 export class HttpHandler {
-  protected _routes: RoutingTable = new RoutingTable();
+  /**
+   * Shared OpenAPI spec objects as `components`
+   */
+  protected _openApiComponents: ComponentsObject;
 
-  public handleRequest: (
-    request: ServerRequest,
-    response: ServerResponse,
-  ) => Promise<void>;
+  public handleRequest: (request: Request, response: Response) => Promise<void>;
 
-  constructor(protected _rootContext: Context) {
+  constructor(
+    protected readonly _rootContext: Context,
+    protected readonly _serverConfig: RestServerResolvedConfig,
+    protected readonly _routes = new RoutingTable(),
+  ) {
     this.handleRequest = (req, res) => this._handleRequest(req, res);
   }
 
-  registerController(name: ControllerClass, spec: ControllerSpec) {
-    this._routes.registerController(name, spec);
+  registerController<T>(
+    spec: ControllerSpec,
+    controllerCtor: ControllerClass<T>,
+    controllerFactory?: ControllerFactory<T>,
+  ) {
+    this._routes.registerController(spec, controllerCtor, controllerFactory);
   }
 
   registerRoute(route: RouteEntry) {
     this._routes.registerRoute(route);
   }
 
-  describeApiPaths(): PathsObject {
+  /**
+   * @deprecated Use `registerApiComponents`
+   * @param defs Schemas
+   */
+  registerApiDefinitions(defs: SchemasObject) {
+    this.registerApiComponents({schemas: defs});
+  }
+
+  /**
+   * Merge components into the OpenApi spec
+   * @param defs - Components
+   */
+  registerApiComponents(defs: ComponentsObject) {
+    this._openApiComponents = this._openApiComponents ?? {};
+    for (const p in defs) {
+      // Merge each child, such as `schemas`, `parameters`, and `headers`
+      this._openApiComponents[p] = {...this._openApiComponents[p], ...defs[p]};
+    }
+  }
+
+  getApiComponents() {
+    return this._openApiComponents;
+  }
+
+  /**
+   * @deprecated Use `getApiComponents`
+   */
+  getApiDefinitions():
+    | {
+        [schema: string]: SchemaObject | ReferenceObject;
+      }
+    | undefined {
+    return this._openApiComponents?.schemas;
+  }
+
+  describeApiPaths(): PathObject {
     return this._routes.describeApiPaths();
   }
 
-  findRoute(request: ParsedRequest): ResolvedRoute {
-    return this._routes.find(request);
+  findRoute(request: Request): ResolvedRoute {
+    const route = this._routes.find(request);
+    Object.assign(route.schemas, this.getApiDefinitions());
+    return route;
   }
 
   protected async _handleRequest(
-    request: ServerRequest,
-    response: ServerResponse,
+    request: Request,
+    response: Response,
   ): Promise<void> {
-    const parsedRequest: ParsedRequest = parseRequestUrl(request);
-    const requestContext = this._createRequestContext(request, response);
+    const requestContext = new RequestContext(
+      request,
+      response,
+      this._rootContext,
+      this._serverConfig,
+    );
 
-    const sequence: SequenceHandler = await requestContext.get(
+    const sequence = await requestContext.get<SequenceHandler>(
       RestBindings.SEQUENCE,
     );
-    await sequence.handle(parsedRequest, response);
-  }
-
-  protected _createRequestContext(
-    req: ServerRequest,
-    res: ServerResponse,
-  ): Context {
-    const requestContext = new Context(this._rootContext);
-    requestContext.bind(RestBindings.Http.REQUEST).to(req);
-    requestContext.bind(RestBindings.Http.RESPONSE).to(res);
-    requestContext.bind(RestBindings.Http.CONTEXT).to(requestContext);
-    return requestContext;
+    await sequence.handle(requestContext);
   }
 }

package/src/index.ts

@@ -1,37 +1,44 @@
-// 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
 
-// external dependencies
-export {ServerRequest, ServerResponse} from 'http';
-
-export {
-  RouteEntry,
-  RoutingTable,
-  Route,
-  ControllerRoute,
-  ResolvedRoute,
-  createResolvedRoute,
-  parseRequestUrl,
-} from './router/routing-table';
-
-export * from './router/metadata';
-export * from './providers';
-
-// import all errors from external http-errors package
-import * as HttpErrors from 'http-errors';
-
-export * from './parser';
-
-export {writeResultToResponse} from './writer';
-
-// http errors
-export {HttpErrors};
-
+/**
+ * The REST API package for loopback-next.
+ *
+ * @remarks
+ * A REST server for LoopBack 4 application instances, complete with:
+ *
+ * - new custom routing engine (special thanks to @bajtos)!
+ * - tools for defining your application routes
+ * - OpenAPI 3.0 spec (openapi.json/openapi.yaml) generation using
+ *   @loopback/openapi-v3
+ * - a default sequence implementation to manage the request and response
+ *   lifecycle
+ *
+ *
+ * @packageDocumentation
+ */
+
+export * from '@loopback/openapi-v3';
+export * from './body-parsers';
 export * from './http-handler';
-export * from './internal-types';
 export * from './keys';
-export * from './rest-component';
-export * from './rest-server';
+export * from './parse-json';
+export * from './parser';
+export * from './providers';
+export * from './request-context';
+export * from './rest-http-error';
+export * from './rest.application';
+export * from './rest.component';
+export * from './rest.server';
+export * from './router';
 export * from './sequence';
+export * from './spec-enhancers/info.spec-enhancer';
+export * from './types';
+export * from './validation/request-body.validator';
+export * from './writer';
+export {HttpErrors};
+
+// export all errors from external http-errors package
+import HttpErrors from 'http-errors';

package/src/keys.ts

@@ -1,36 +1,289 @@
-// 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 {BindingKey, Context} from '@loopback/context';
 import {CoreBindings} from '@loopback/core';
+import {InvokeMiddleware} from '@loopback/express';
+import {HttpProtocol} from '@loopback/http-server';
+import {OpenApiSpec, OperationObject} from '@loopback/openapi-v3';
+import https from 'https';
+import {ErrorWriterOptions} from 'strong-error-handler';
+import {BodyParser, RequestBodyParser} from './body-parsers';
+import {HttpHandler} from './http-handler';
+import {RestServer, RestServerConfig} from './rest.server';
+import {RestRouter, RestRouterOptions} from './router';
+import {SequenceHandler} from './sequence';
+import {
+  AjvFactory,
+  FindRoute,
+  InvokeMethod,
+  LogError,
+  ParseParams,
+  Reject,
+  Request,
+  RequestBodyParserOptions,
+  Response,
+  Send,
+} from './types';
 
+/**
+ * RestServer-specific bindings
+ */
 export namespace RestBindings {
-  // RestServer-specific bindings
-  export const CONFIG = `${CoreBindings.APPLICATION_CONFIG}#rest`;
-  export const PORT = 'rest.port';
-  export const HANDLER = 'rest.handler';
+  /**
+   * Binding key for setting and injecting RestComponentConfig
+   */
+  export const CONFIG: BindingKey<RestServerConfig> = CoreBindings.APPLICATION_CONFIG.deepProperty(
+    'rest',
+  );
+  /**
+   * Binding key for setting and injecting the host name of RestServer
+   */
+  export const HOST = BindingKey.create<string | undefined>('rest.host');
+  /**
+   * Binding key for setting and injecting the port number of RestServer
+   */
+  export const PORT = BindingKey.create<number>('rest.port');
+  /**
+   * Binding key for setting and injecting the socket path of the RestServer
+   */
+  export const PATH = BindingKey.create<string | undefined>('rest.path');
+  /**
+   * Binding key for setting and injecting the URL of RestServer
+   */
+  export const URL = BindingKey.create<string>('rest.url');
+  /**
+   * Binding key for setting and injecting the protocol of RestServer
+   */
+  export const PROTOCOL = BindingKey.create<HttpProtocol>('rest.protocol');
+  /**
+   * Binding key for HTTPS options
+   */
+  export const HTTPS_OPTIONS = BindingKey.create<https.ServerOptions>(
+    'rest.httpsOptions',
+  );
 
-  export const API_SPEC = 'rest.apiSpec';
-  export const SEQUENCE = 'rest.sequence';
+  /**
+   * Binding key for the server itself
+   */
+  export const SERVER = BindingKey.create<RestServer>('servers.RestServer');
 
-  export namespace SequenceActions {
-    export const FIND_ROUTE = 'rest.sequence.actions.findRoute';
-    export const PARSE_PARAMS = 'rest.sequence.actions.parseParams';
-    export const INVOKE_METHOD = 'rest.sequence.actions.invokeMethod';
-    export const LOG_ERROR = 'rest.sequence.actions.logError';
-    export const SEND = 'rest.sequence.actions.send';
-    export const REJECT = 'rest.sequence.actions.reject';
+  /**
+   * Internal binding key for basePath
+   */
+  export const BASE_PATH = BindingKey.create<string>('rest.basePath');
+
+  /**
+   * Internal binding key for http-handler
+   */
+  export const HANDLER = BindingKey.create<HttpHandler>('rest.handler');
+
+  /**
+   * Internal binding key for rest router
+   */
+  export const ROUTER = BindingKey.create<RestRouter>('rest.router');
+
+  export const ROUTER_OPTIONS = BindingKey.create<RestRouterOptions>(
+    'rest.router.options',
+  );
+
+  /**
+   * Binding key for setting and injecting Reject action's error handling
+   * options.
+   *
+   * See https://github.com/strongloop/strong-error-handler#options for
+   * the list of available options. Please note that the flag `log` is not used
+   * by `@loopback/rest`.
+   */
+  export const ERROR_WRITER_OPTIONS = BindingKey.create<ErrorWriterOptions>(
+    'rest.errorWriterOptions',
+  );
+
+  /**
+   * Binding key for request body parser options
+   */
+  export const REQUEST_BODY_PARSER_OPTIONS = BindingKey.create<
+    RequestBodyParserOptions
+  >('rest.requestBodyParserOptions');
+
+  /**
+   * Binding key for request body parser
+   */
+  export const REQUEST_BODY_PARSER = BindingKey.create<RequestBodyParser>(
+    'rest.requestBodyParser',
+  );
+
+  function bodyParserBindingKey(parser: string) {
+    return `${REQUEST_BODY_PARSER}.${parser}`;
   }
 
-  export const GET_FROM_CONTEXT = 'getFromContext';
-  export const BIND_ELEMENT = 'bindElement';
+  /**
+   * Binding key for request json body parser
+   */
+  export const REQUEST_BODY_PARSER_JSON = BindingKey.create<BodyParser>(
+    bodyParserBindingKey('JsonBodyParser'),
+  );
+
+  /**
+   * Binding key for request urlencoded body parser
+   */
+  export const REQUEST_BODY_PARSER_URLENCODED = BindingKey.create<BodyParser>(
+    bodyParserBindingKey('UrlEncodedBodyParser'),
+  );
+
+  /**
+   * Binding key for request text body parser
+   */
+  export const REQUEST_BODY_PARSER_TEXT = BindingKey.create<BodyParser>(
+    bodyParserBindingKey('TextBodyParser'),
+  );
+
+  /**
+   * Binding key for request raw body parser
+   */
+  export const REQUEST_BODY_PARSER_RAW = BindingKey.create<BodyParser>(
+    bodyParserBindingKey('RawBodyParser'),
+  );
+
+  /**
+   * Binding key for request raw body parser
+   */
+  export const REQUEST_BODY_PARSER_STREAM = BindingKey.create<BodyParser>(
+    bodyParserBindingKey('StreamBodyParser'),
+  );
+
+  /**
+   * Binding key for AJV
+   */
+  export const AJV_FACTORY = BindingKey.create<AjvFactory>(
+    bodyParserBindingKey('rest.ajvFactory'),
+  );
 
-  // request-specific bindings
+  /**
+   * Binding key for setting and injecting an OpenAPI spec
+   */
+  export const API_SPEC: BindingKey<OpenApiSpec> = BindingKey.create<
+    OpenApiSpec
+  >('rest.apiSpec');
 
+  /**
+   * Binding key for setting and injecting an OpenAPI operation spec
+   */
+  export const OPERATION_SPEC_CURRENT = BindingKey.create<OperationObject>(
+    'rest.operationSpec.current',
+  );
+
+  /**
+   * Binding key for setting and injecting a Sequence
+   */
+  export const SEQUENCE = BindingKey.create<SequenceHandler>('rest.sequence');
+
+  /**
+   * Bindings for potential actions that could be used in a sequence
+   */
+  export namespace SequenceActions {
+    /**
+     * Binding key for setting and injecting a route finding function
+     */
+    export const INVOKE_MIDDLEWARE = BindingKey.create<InvokeMiddleware>(
+      'rest.sequence.actions.invokeMiddleware',
+    );
+    /**
+     * Binding key for setting and injecting a route finding function
+     */
+    export const FIND_ROUTE = BindingKey.create<FindRoute>(
+      'rest.sequence.actions.findRoute',
+    );
+    /**
+     * Binding key for setting and injecting a parameter parsing function
+     */
+    export const PARSE_PARAMS = BindingKey.create<ParseParams>(
+      'rest.sequence.actions.parseParams',
+    );
+    /**
+     * Binding key for setting and injecting a controller route invoking function
+     */
+    export const INVOKE_METHOD = BindingKey.create<InvokeMethod>(
+      'rest.sequence.actions.invokeMethod',
+    );
+    /**
+     * Binding key for setting and injecting an error logging function
+     */
+    export const LOG_ERROR = BindingKey.create<LogError>(
+      'rest.sequence.actions.logError',
+    );
+    /**
+     * Binding key for setting and injecting a response writing function
+     */
+    export const SEND = BindingKey.create<Send>('rest.sequence.actions.send');
+    /**
+     * Binding key for setting and injecting a bad response writing function
+     */
+    export const REJECT = BindingKey.create<Reject>(
+      'rest.sequence.actions.reject',
+    );
+  }
+
+  /**
+   * Request-specific bindings
+   */
   export namespace Http {
-    export const REQUEST = 'rest.http.request';
-    export const RESPONSE = 'rest.http.response';
-    export const CONTEXT = 'rest.http.request.context';
+    /**
+     * Binding key for setting and injecting the http request
+     */
+    export const REQUEST: BindingKey<Request> = BindingKey.create<Request>(
+      'rest.http.request',
+    );
+    /**
+     * Binding key for setting and injecting the http response
+     */
+    export const RESPONSE = BindingKey.create<Response>('rest.http.response');
+    /**
+     * Binding key for setting and injecting the http request context
+     */
+    export const CONTEXT = BindingKey.create<Context>(
+      'rest.http.request.context',
+    );
   }
+
+  /**
+   * Namespace for REST routes
+   */
+  export const ROUTES = 'routes';
+}
+
+/**
+ * Binding tags for RestServer
+ */
+export namespace RestTags {
+  /**
+   * Binding tag to identify REST routes
+   */
+  export const REST_ROUTE = 'restRoute';
+
+  /**
+   * Binding tag for the REST route verb
+   */
+  export const ROUTE_VERB = 'restRouteVerb';
+
+  /**
+   * Binding tag for the REST route path
+   */
+  export const ROUTE_PATH = 'restRoutePath';
+
+  /**
+   * Binding tag to identify controller based REST routes
+   */
+  export const CONTROLLER_ROUTE = 'controllerRoute';
+
+  /**
+   * Binding tag for controller route bindings to represent the controller
+   * binding key
+   */
+  export const CONTROLLER_BINDING = 'controllerBinding';
+
+  export const AJV_KEYWORD = 'ajvKeyword';
+  export const AJV_FORMAT = 'ajvFormat';
 }

package/src/parse-json.ts

@@ -0,0 +1,42 @@
+// 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
+
+/* eslint-disable @typescript-eslint/no-explicit-any */
+
+// These utilities are introduced to mitigate the prototype pollution issue
+// with `JSON.parse`.
+// See https://hueniverse.com/a-tale-of-prototype-poisoning-2610fa170061
+//
+// The [bourne](https://github.com/hapijs/bourne) module provides a drop-in
+// replacement for `JSON.parse` but we need to instruct `body-parser` to honor
+// a `reviver` function.
+
+/**
+ * Factory to create a reviver function for `JSON.parse` to sanitize keys
+ * @param reviver - Reviver function
+ */
+export function sanitizeJsonParse(reviver?: (key: any, value: any) => any) {
+  return (key: string, value: any) => {
+    if (key === '__proto__')
+      throw new Error('JSON string cannot contain "__proto__" key.');
+    if (reviver) {
+      return reviver(key, value);
+    } else {
+      return value;
+    }
+  };
+}
+
+/**
+ *
+ * @param text - JSON string
+ * @param reviver - Optional reviver function for `JSON.parse`
+ */
+export function parseJson(
+  text: string,
+  reviver?: (key: any, value: any) => any,
+) {
+  return JSON.parse(text, sanitizeJsonParse(reviver));
+}