@loopback/rest 4.0.0-alpha.8 → 5.0.1

package/src/parser.ts

@@ -1,135 +1,120 @@
-// 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 {ServerRequest} from 'http';
-import {HttpErrors} from './';
-import {OperationObject, ParameterObject} from '@loopback/openapi-spec';
-import {promisify} from '@loopback/core';
+import {
+  isReferenceObject,
+  OperationObject,
+  ParameterObject,
+  REQUEST_BODY_INDEX,
+  SchemasObject,
+} from '@loopback/openapi-v3';
+import debugFactory from 'debug';
+import {RequestBody, RequestBodyParser} from './body-parsers';
+import {coerceParameter} from './coercion/coerce-parameter';
+import {RestHttpErrors} from './rest-http-error';
+import {ResolvedRoute} from './router';
 import {
   OperationArgs,
-  ParsedRequest,
   PathParameterValues,
-} from './internal-types';
-import {ResolvedRoute} from './router/routing-table';
-type HttpError = HttpErrors.HttpError;
-
-type jsonBodyFn = (
-  req: ServerRequest,
-  cb: (err?: Error, body?: {}) => void,
-) => void;
-const jsonBody: jsonBodyFn = require('body/json');
-
-// tslint:disable:no-any
-type MaybeBody = any | undefined;
-// tslint:enable:no-any
-
-const parseJsonBody: (req: ServerRequest) => Promise<MaybeBody> = promisify(
-  jsonBody,
-);
-
-/**
- * Get the content-type header value from the request
- * @param req Http request
- */
-function getContentType(req: ServerRequest): string | undefined {
-  const val = req.headers['content-type'];
-  if (typeof val === 'string') {
-    return val;
-  } else if (Array.isArray(val)) {
-    // Assume only one value is present
-    return val[0];
-  }
-  return undefined;
-}
+  Request,
+  RequestBodyValidationOptions,
+} from './types';
+import {validateRequestBody} from './validation/request-body.validator';
+const debug = debugFactory('loopback:rest:parser');
 
 /**
  * Parses the request to derive arguments to be passed in for the Application
  * controller method
  *
- * @param request Incoming HTTP request
- * @param operationSpec Swagger spec defined in the controller
- * @param pathParams Path parameters in incoming HTTP request
+ * @param request - Incoming HTTP request
+ * @param route - Resolved Route
  */
 export async function parseOperationArgs(
-  request: ParsedRequest,
+  request: Request,
   route: ResolvedRoute,
+  requestBodyParser: RequestBodyParser = new RequestBodyParser(),
+  options: RequestBodyValidationOptions = {},
 ): Promise<OperationArgs> {
+  debug('Parsing operation arguments for route %s', route.describe());
   const operationSpec = route.spec;
   const pathParams = route.pathParams;
-  const body = await loadRequestBodyIfNeeded(operationSpec, request);
-  return buildOperationArguments(operationSpec, request, pathParams, body);
+  const body = await requestBodyParser.loadRequestBodyIfNeeded(
+    operationSpec,
+    request,
+  );
+  return buildOperationArguments(
+    operationSpec,
+    request,
+    pathParams,
+    body,
+    route.schemas,
+    options,
+  );
 }
 
-function loadRequestBodyIfNeeded(
+async function buildOperationArguments(
   operationSpec: OperationObject,
-  request: ServerRequest,
-): Promise<MaybeBody> {
-  if (!hasArgumentsFromBody(operationSpec)) return Promise.resolve();
-
-  const contentType = getContentType(request);
-  if (contentType && !/json/.test(contentType)) {
-    const err = new HttpErrors.UnsupportedMediaType(
-      `Content-type ${contentType} is not supported.`,
-    );
-    return Promise.reject(err);
-  }
-
-  return parseJsonBody(request).catch((err: HttpError) => {
-    err.statusCode = 400;
-    return Promise.reject(err);
-  });
-}
-
-function hasArgumentsFromBody(operationSpec: OperationObject): boolean {
-  if (!operationSpec.parameters || !operationSpec.parameters.length)
-    return false;
-
-  for (const paramSpec of operationSpec.parameters) {
-    if ('$ref' in paramSpec) continue;
-    const source = (paramSpec as ParameterObject).in;
-    if (source === 'formData' || source === 'body') return true;
+  request: Request,
+  pathParams: PathParameterValues,
+  body: RequestBody,
+  globalSchemas: SchemasObject,
+  options: RequestBodyValidationOptions = {},
+): Promise<OperationArgs> {
+  let requestBodyIndex = -1;
+  if (operationSpec.requestBody) {
+    // the type of `operationSpec.requestBody` could be `RequestBodyObject`
+    // or `ReferenceObject`, resolving a `$ref` value is not supported yet.
+    if (isReferenceObject(operationSpec.requestBody)) {
+      throw new Error('$ref requestBody is not supported yet.');
+    }
+    const i = operationSpec.requestBody[REQUEST_BODY_INDEX];
+    requestBodyIndex = i ? i : 0;
   }
-  return false;
-}
 
-function buildOperationArguments(
-  operationSpec: OperationObject,
-  request: ParsedRequest,
-  pathParams: PathParameterValues,
-  body?: MaybeBody,
-): OperationArgs {
-  const args: OperationArgs = [];
+  const paramArgs: OperationArgs = [];
 
-  for (const paramSpec of operationSpec.parameters || []) {
-    if ('$ref' in paramSpec) {
+  for (const paramSpec of operationSpec.parameters ?? []) {
+    if (isReferenceObject(paramSpec)) {
       // TODO(bajtos) implement $ref parameters
       // See https://github.com/strongloop/loopback-next/issues/435
       throw new Error('$ref parameters are not supported yet.');
     }
     const spec = paramSpec as ParameterObject;
-    switch (spec.in) {
-      case 'query':
-        args.push(request.query[spec.name]);
-        break;
-      case 'path':
-        args.push(pathParams[spec.name]);
-        break;
-      case 'header':
-        args.push(request.headers[spec.name.toLowerCase()]);
-        break;
-      case 'formData':
-        args.push(body ? body[spec.name] : undefined);
-        break;
-      case 'body':
-        args.push(body);
-        break;
-      default:
-        throw new HttpErrors.NotImplemented(
-          'Parameters with "in: ' + spec.in + '" are not supported yet.',
-        );
-    }
+    const rawValue = getParamFromRequest(spec, request, pathParams);
+    const coercedValue = coerceParameter(rawValue, spec);
+    paramArgs.push(coercedValue);
+  }
+
+  debug('Validating request body - value %j', body);
+  await validateRequestBody(
+    body,
+    operationSpec.requestBody,
+    globalSchemas,
+    options,
+  );
+
+  if (requestBodyIndex > -1) paramArgs.splice(requestBodyIndex, 0, body.value);
+  return paramArgs;
+}
+
+function getParamFromRequest(
+  spec: ParameterObject,
+  request: Request,
+  pathParams: PathParameterValues,
+) {
+  switch (spec.in) {
+    case 'query':
+      return request.query[spec.name];
+    case 'path':
+      return pathParams[spec.name];
+    case 'header':
+      // @jannyhou TBD: check edge cases
+      return request.headers[spec.name.toLowerCase()];
+    // TODO(jannyhou) to support `cookie`,
+    // see issue https://github.com/strongloop/loopback-next/issues/997
+    default:
+      throw RestHttpErrors.invalidParamLocation(spec.in);
   }
-  return args;
 }

package/src/providers/{find-route.ts → find-route.provider.ts}

@@ -1,12 +1,13 @@
-// Copyright IBM Corp. 2017. All Rights Reserved.
+// 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, inject, Provider} from '@loopback/context';
-import {FindRoute} from '../internal-types';
+import {FindRoute, Request} from '../types';
 import {HttpHandler} from '../http-handler';
 import {RestBindings} from '../keys';
+import {ResolvedRoute} from '../router';
 
 export class FindRouteProvider implements Provider<FindRoute> {
   constructor(
@@ -15,10 +16,12 @@ export class FindRouteProvider implements Provider<FindRoute> {
   ) {}
 
   value(): FindRoute {
-    return request => {
-      const found = this.handler.findRoute(request);
-      found.updateBindings(this.context);
-      return found;
-    };
+    return request => this.action(request);
+  }
+
+  action(request: Request): ResolvedRoute {
+    const found = this.handler.findRoute(request);
+    found.updateBindings(this.context);
+    return found;
   }
 }

package/src/providers/index.ts

@@ -1,13 +1,11 @@
-// Copyright IBM Corp. 2013,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
 
-export * from './bind-element';
-export * from './find-route';
-export * from './get-from-context';
-export * from './invoke-method';
-export * from './log-error-provider';
-export * from './reject';
-export * from './parse-params';
-export * from './send';
+export * from './find-route.provider';
+export * from './invoke-method.provider';
+export * from './log-error.provider';
+export * from './parse-params.provider';
+export * from './reject.provider';
+export * from './send.provider';

package/src/providers/{invoke-method.ts → invoke-method.provider.ts}

@@ -1,18 +1,21 @@
-// Copyright IBM Corp. 2017. All Rights Reserved.
+// 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, inject, Provider} from '@loopback/context';
-import {InvokeMethod} from '../internal-types';
+import {InvokeMethod, OperationArgs, OperationRetval} from '../types';
 import {RestBindings} from '../keys';
+import {RouteEntry} from '../router';
 
 export class InvokeMethodProvider implements Provider<InvokeMethod> {
   constructor(@inject(RestBindings.Http.CONTEXT) protected context: Context) {}
 
   value(): InvokeMethod {
-    return async (route, args) => {
-      return await route.invokeHandler(this.context, args);
-    };
+    return (route, args) => this.action(route, args);
+  }
+
+  action(route: RouteEntry, args: OperationArgs): Promise<OperationRetval> {
+    return route.invokeHandler(this.context, args);
   }
 }

package/src/providers/log-error.provider.ts

@@ -0,0 +1,27 @@
+// 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 {Provider} from '@loopback/context';
+import {LogError, Request} from '../types';
+
+export class LogErrorProvider implements Provider<LogError> {
+  value(): LogError {
+    return (err, statusCode, req) => this.action(err, statusCode, req);
+  }
+
+  action(err: Error, statusCode: number, req: Request) {
+    if (statusCode < 500) {
+      return;
+    }
+
+    console.error(
+      'Unhandled error in %s %s: %s %s',
+      req.method,
+      req.url,
+      statusCode,
+      err.stack ?? err,
+    );
+  }
+}

package/src/providers/parse-params.provider.ts

@@ -0,0 +1,42 @@
+// 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 {inject, Provider} from '@loopback/context';
+import {RequestBodyParser} from '../body-parsers';
+import {RestBindings} from '../keys';
+import {parseOperationArgs} from '../parser';
+import {ResolvedRoute} from '../router';
+import {
+  AjvFactory,
+  ParseParams,
+  Request,
+  RequestBodyValidationOptions,
+} from '../types';
+/**
+ * Provides the function for parsing args in requests at runtime.
+ *
+ * @returns The handler function that will parse request args.
+ */
+export class ParseParamsProvider implements Provider<ParseParams> {
+  constructor(
+    @inject(RestBindings.REQUEST_BODY_PARSER)
+    private requestBodyParser: RequestBodyParser,
+    @inject(
+      RestBindings.REQUEST_BODY_PARSER_OPTIONS.deepProperty('validation'),
+      {optional: true},
+    )
+    private validationOptions: RequestBodyValidationOptions = {},
+    @inject(RestBindings.AJV_FACTORY, {optional: true})
+    private ajvFactory?: AjvFactory,
+  ) {}
+
+  value(): ParseParams {
+    return (request: Request, route: ResolvedRoute) =>
+      parseOperationArgs(request, route, this.requestBodyParser, {
+        ajvFactory: this.ajvFactory,
+        ...this.validationOptions,
+      });
+  }
+}

package/src/providers/reject.provider.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 {LogError, Reject, HandlerContext} from '../types';
+import {inject, Provider} from '@loopback/context';
+import {HttpError} from 'http-errors';
+import {RestBindings} from '../keys';
+import {writeErrorToResponse, ErrorWriterOptions} from 'strong-error-handler';
+
+// TODO(bajtos) Make this mapping configurable at RestServer level,
+// allow apps and extensions to contribute additional mappings.
+const codeToStatusCodeMap: {[key: string]: number} = {
+  ENTITY_NOT_FOUND: 404,
+};
+
+export class RejectProvider implements Provider<Reject> {
+  constructor(
+    @inject(RestBindings.SequenceActions.LOG_ERROR)
+    protected logError: LogError,
+    @inject(RestBindings.ERROR_WRITER_OPTIONS, {optional: true})
+    protected errorWriterOptions?: ErrorWriterOptions,
+  ) {}
+
+  value(): Reject {
+    return (context, error) => this.action(context, error);
+  }
+
+  action({request, response}: HandlerContext, error: Error) {
+    const err = <HttpError>error;
+
+    if (!err.status && !err.statusCode && err.code) {
+      const customStatus = codeToStatusCodeMap[err.code];
+      if (customStatus) {
+        err.statusCode = customStatus;
+      }
+    }
+
+    const statusCode = err.statusCode || err.status || 500;
+    writeErrorToResponse(err, request, response, this.errorWriterOptions);
+    this.logError(error, statusCode, request);
+  }
+}

package/src/providers/{send.ts → send.provider.ts}

@@ -1,4 +1,4 @@
-// Copyright IBM Corp. 2017. All Rights Reserved.
+// 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
@@ -9,10 +9,7 @@ import {writeResultToResponse} from '../writer';
  * Provides the function that populates the response object with
  * the results of the operation.
  *
- * @export
- * @class SendProvider
- * @implements {Provider<BoundValue>}
- * @returns {BoundValue} The handler function that will populate the
+ * @returns The handler function that will populate the
  * response with operation results.
  */
 export class SendProvider implements Provider<BoundValue> {

package/src/request-context.ts

@@ -0,0 +1,123 @@
+// 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 {
+  HandlerContext,
+  MiddlewareContext,
+  Request,
+  Response,
+} from '@loopback/express';
+import {RestBindings} from './keys';
+import {RestServerResolvedConfig} from './rest.server';
+
+/**
+ * A per-request Context combining an IoC container with handler context
+ * (request, response, etc.).
+ */
+export class RequestContext extends MiddlewareContext
+  implements HandlerContext {
+  /**
+   * Get the protocol used by the client to make the request.
+   * Please note this protocol may be different from what we are observing
+   * at HTTP/TCP level, because reverse proxies like nginx or sidecars like
+   * Envoy are switching between protocols.
+   */
+  get requestedProtocol(): string {
+    return (
+      ((this.request.get('x-forwarded-proto') ?? '').split(',')[0] ||
+        this.request.protocol ||
+        this.serverConfig.protocol) ??
+      'http'
+    );
+  }
+
+  /**
+   * Get the effective base path of the incoming request. This base path
+   * combines `baseUrl` provided by Express when LB4 handler is mounted on
+   * a non-root path, with the `basePath` value configured at LB4 side.
+   */
+  get basePath(): string {
+    const request = this.request;
+    let basePath = this.serverConfig.basePath ?? '';
+    if (request.baseUrl && request.baseUrl !== '/') {
+      if (!basePath || request.baseUrl.endsWith(basePath)) {
+        // Express has already applied basePath to baseUrl
+        basePath = request.baseUrl;
+      } else {
+        basePath = request.baseUrl + basePath;
+      }
+    }
+    return basePath;
+  }
+
+  /**
+   * Get the base URL used by the client to make the request.
+   * This URL contains the protocol, hostname, port and base path.
+   * The path of the invoked route and query string is not included.
+   *
+   * Please note these values may be different from what we are observing
+   * at HTTP/TCP level, because reverse proxies like nginx are rewriting them.
+   */
+  get requestedBaseUrl(): string {
+    const request = this.request;
+    const config = this.serverConfig;
+
+    const protocol = this.requestedProtocol;
+    // The host can be in one of the forms
+    // [::1]:3000
+    // [::1]
+    // 127.0.0.1:3000
+    // 127.0.0.1
+    let {host, port} = parseHostAndPort(
+      request.get('x-forwarded-host') ?? request.headers.host,
+    );
+
+    const forwardedPort = (request.get('x-forwarded-port') ?? '').split(',')[0];
+    port = forwardedPort || port;
+
+    if (!host) {
+      // No host detected from http headers
+      // Use the configured values or the local network address
+      host = config.host ?? request.socket.localAddress;
+      port = (config.port || request.socket.localPort).toString();
+    }
+
+    // clear default ports
+    port = protocol === 'https' && port === '443' ? '' : port;
+    port = protocol === 'http' && port === '80' ? '' : port;
+
+    // add port number of present
+    host += port !== '' ? ':' + port : '';
+
+    return protocol + '://' + host + this.basePath;
+  }
+
+  constructor(
+    public readonly request: Request,
+    public readonly response: Response,
+    parent: Context,
+    public readonly serverConfig: RestServerResolvedConfig,
+    name?: string,
+  ) {
+    super(request, response, parent, name);
+  }
+
+  protected setupBindings() {
+    super.setupBindings();
+    this.bind(RestBindings.Http.REQUEST).to(this.request).lock();
+    this.bind(RestBindings.Http.RESPONSE).to(this.response).lock();
+    this.bind(RestBindings.Http.CONTEXT).to(this).lock();
+  }
+}
+
+function parseHostAndPort(host: string | undefined) {
+  host = host ?? '';
+  host = host.split(',')[0];
+  const portPattern = /:([0-9]+)$/;
+  const port = (host.match(portPattern) ?? [])[1] || '';
+  host = host.replace(portPattern, '');
+  return {host, port};
+}

package/src/rest-http-error.ts

@@ -0,0 +1,87 @@
+// 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 HttpErrors from 'http-errors';
+
+export namespace RestHttpErrors {
+  export function invalidData<T, Props extends object = {}>(
+    data: T,
+    name: string,
+    extraProperties?: Props,
+  ): HttpErrors.HttpError & Props {
+    const msg = `Invalid data ${JSON.stringify(data)} for parameter ${name}!`;
+    return Object.assign(
+      new HttpErrors.BadRequest(msg),
+      {
+        code: 'INVALID_PARAMETER_VALUE',
+        parameterName: name,
+      },
+      extraProperties,
+    );
+  }
+
+  export function unsupportedMediaType(
+    contentType: string,
+    allowedTypes: string[] = [],
+  ) {
+    const msg = allowedTypes?.length
+      ? `Content-type ${contentType} does not match [${allowedTypes}].`
+      : `Content-type ${contentType} is not supported.`;
+    return Object.assign(new HttpErrors.UnsupportedMediaType(msg), {
+      code: 'UNSUPPORTED_MEDIA_TYPE',
+      contentType: contentType,
+      allowedMediaTypes: allowedTypes,
+    });
+  }
+
+  export function missingRequired(name: string): HttpErrors.HttpError {
+    const msg = `Required parameter ${name} is missing!`;
+    return Object.assign(new HttpErrors.BadRequest(msg), {
+      code: 'MISSING_REQUIRED_PARAMETER',
+      parameterName: name,
+    });
+  }
+
+  export function invalidParamLocation(location: string): HttpErrors.HttpError {
+    const msg = `Parameters with "in: ${location}" are not supported yet.`;
+    return new HttpErrors.NotImplemented(msg);
+  }
+
+  export const INVALID_REQUEST_BODY_MESSAGE =
+    'The request body is invalid. See error object `details` property for more info.';
+  export function invalidRequestBody(): HttpErrors.HttpError {
+    return Object.assign(
+      new HttpErrors.UnprocessableEntity(INVALID_REQUEST_BODY_MESSAGE),
+      {
+        code: 'VALIDATION_FAILED',
+      },
+    );
+  }
+
+  /**
+   * An invalid request body error contains a `details` property as the machine-readable error.
+   * Each entry in `error.details` contains 4 attributes: `path`, `code`, `info` and `message`.
+   * `ValidationErrorDetails` defines the type of each entry, which is an object.
+   * The type of `error.details` is `ValidationErrorDetails[]`.
+   */
+  export interface ValidationErrorDetails {
+    /**
+     * A path to the invalid field.
+     */
+    path: string;
+    /**
+     * A single word code represents the error's type.
+     */
+    code: string;
+    /**
+     * A human readable description of the error.
+     */
+    message: string;
+    /**
+     * Some additional details that the 3 attributes above don't cover.
+     */
+    info: object;
+  }
+}