@loopback/rest 4.0.0-alpha.8 → 5.0.1

package/src/body-parsers/body-parser.text.ts

@@ -0,0 +1,44 @@
+// Copyright IBM Corp. 2018. 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} from '@loopback/context';
+import {text} from 'body-parser';
+import {is} from 'type-is';
+import {RestBindings} from '../keys';
+import {Request, RequestBodyParserOptions} from '../types';
+import {
+  BodyParserMiddleware,
+  getParserOptions,
+  invokeBodyParserMiddleware,
+  builtinParsers,
+} from './body-parser.helpers';
+import {BodyParser, RequestBody} from './types';
+
+export class TextBodyParser implements BodyParser {
+  name = builtinParsers.text;
+  private textParser: BodyParserMiddleware;
+
+  constructor(
+    @inject(RestBindings.REQUEST_BODY_PARSER_OPTIONS, {optional: true})
+    options: RequestBodyParserOptions = {},
+  ) {
+    const textOptions = Object.assign(
+      {type: 'text/*'},
+      getParserOptions('text', options),
+    );
+    this.textParser = text(textOptions);
+  }
+
+  supports(mediaType: string) {
+    // Please note that `text/*` matches `text/plain` and `text/html` but`text`
+    // does not.
+    return !!is(mediaType, 'text/*');
+  }
+
+  async parse(request: Request): Promise<RequestBody> {
+    const body = await invokeBodyParserMiddleware(this.textParser, request);
+    return {value: body};
+  }
+}

package/src/body-parsers/body-parser.ts

@@ -0,0 +1,208 @@
+// 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 {
+  compareByOrder,
+  Constructor,
+  Context,
+  filterByTag,
+  inject,
+  instantiateClass,
+} from '@loopback/context';
+import {isReferenceObject, OperationObject} from '@loopback/openapi-v3';
+import debugModule from 'debug';
+import {is} from 'type-is';
+import {RestHttpErrors} from '../rest-http-error';
+import {Request} from '../types';
+import {
+  builtinParsers,
+  getContentType,
+  normalizeParsingError,
+} from './body-parser.helpers';
+import {
+  BodyParser,
+  BodyParserFunction,
+  RequestBody,
+  REQUEST_BODY_PARSER_TAG,
+} from './types';
+
+const debug = debugModule('loopback:rest:body-parser');
+
+export class RequestBodyParser {
+  readonly parsers: BodyParser[];
+
+  constructor(
+    @inject(filterByTag(REQUEST_BODY_PARSER_TAG), {optional: true})
+    parsers?: BodyParser[],
+    @inject.context() private readonly ctx?: Context,
+  ) {
+    this.parsers = sortParsers(parsers ?? []);
+    if (debug.enabled) {
+      debug(
+        'Body parsers: ',
+        this.parsers.map(p => p.name),
+      );
+    }
+  }
+
+  async loadRequestBodyIfNeeded(
+    operationSpec: OperationObject,
+    request: Request,
+  ): Promise<RequestBody> {
+    const {requestBody, customParser} = await this._matchRequestBodySpec(
+      operationSpec,
+      request,
+    );
+    if (!operationSpec.requestBody) return requestBody;
+    const matchedMediaType = requestBody.mediaType!;
+    try {
+      if (customParser) {
+        // Invoke the custom parser
+        const body = await this._invokeCustomParser(customParser, request);
+        return Object.assign(requestBody, body);
+      } else {
+        const parser = this._findParser(matchedMediaType);
+        if (parser) {
+          const body = await parser.parse(request);
+          return Object.assign(requestBody, body);
+        }
+      }
+    } catch (err) {
+      throw normalizeParsingError(err);
+    }
+
+    throw RestHttpErrors.unsupportedMediaType(matchedMediaType);
+  }
+
+  /**
+   * Match the http request to a given media type of the request body spec
+   */
+  private async _matchRequestBodySpec(
+    operationSpec: OperationObject,
+    request: Request,
+  ) {
+    const requestBody: RequestBody = {
+      value: undefined,
+    };
+    if (!operationSpec.requestBody) return {requestBody};
+
+    const contentType = getContentType(request) ?? 'application/json';
+    debug('Loading request body with content type %j', contentType);
+
+    // 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.');
+    }
+
+    let content = operationSpec.requestBody.content || {};
+    if (!Object.keys(content).length) {
+      content = {
+        // default to allow json and urlencoded
+        'application/json': {schema: {type: 'object'}},
+        'application/x-www-form-urlencoded': {schema: {type: 'object'}},
+      };
+    }
+
+    // Check of the request content type matches one of the expected media
+    // types in the request body spec
+    let matchedMediaType: string | false = false;
+    let customParser = undefined;
+    for (const type in content) {
+      matchedMediaType = is(contentType, type);
+      if (matchedMediaType) {
+        debug('Matched media type: %s -> %s', type, contentType);
+        requestBody.mediaType = contentType;
+        requestBody.schema = content[type].schema;
+        customParser = content[type]['x-parser'];
+        break;
+      }
+    }
+
+    if (!matchedMediaType) {
+      // No matching media type found, fail fast
+      throw RestHttpErrors.unsupportedMediaType(
+        contentType,
+        Object.keys(content),
+      );
+    }
+
+    return {requestBody, customParser};
+  }
+
+  /**
+   * Find a body parser that supports the media type
+   * @param matchedMediaType - Media type
+   */
+  private _findParser(matchedMediaType: string) {
+    for (const parser of this.parsers) {
+      if (!parser.supports(matchedMediaType)) {
+        debug(
+          'Body parser %s does not support %s',
+          parser.name,
+          matchedMediaType,
+        );
+        continue;
+      }
+      debug('Body parser %s found for %s', parser.name, matchedMediaType);
+      return parser;
+    }
+  }
+
+  /**
+   * Resolve and invoke a custom parser
+   * @param customParser - The parser name, class or function
+   * @param request - Http request
+   */
+  private async _invokeCustomParser(
+    customParser: string | Constructor<BodyParser> | BodyParserFunction,
+    request: Request,
+  ) {
+    if (typeof customParser === 'string') {
+      const parser = this.parsers.find(
+        p =>
+          p.name === customParser ||
+          p.name === builtinParsers.mapping[customParser],
+      );
+      if (parser) {
+        debug('Using custom parser %s', customParser);
+        return parser.parse(request);
+      }
+    } else if (typeof customParser === 'function') {
+      if (isBodyParserClass(customParser)) {
+        debug('Using custom parser class %s', customParser.name);
+        const parser = await instantiateClass<BodyParser>(
+          customParser as Constructor<BodyParser>,
+          this.ctx!,
+        );
+        return parser.parse(request);
+      } else {
+        debug('Using custom parser function %s', customParser.name);
+        return customParser(request);
+      }
+    }
+    throw new Error('Custom parser not found: ' + customParser);
+  }
+}
+
+/**
+ * Test if a function is a body parser class or plain function
+ * @param fn
+ */
+function isBodyParserClass(
+  fn: Constructor<BodyParser> | BodyParserFunction,
+): fn is Constructor<BodyParser> {
+  return fn.toString().startsWith('class ');
+}
+
+/**
+ * Sort body parsers so that built-in ones are used after extensions
+ * @param parsers
+ */
+function sortParsers(parsers: BodyParser[]) {
+  return parsers.sort((a, b) =>
+    compareByOrder(a.name, b.name, builtinParsers.names),
+  );
+}

package/src/body-parsers/body-parser.urlencoded.ts

@@ -0,0 +1,42 @@
+// Copyright IBM Corp. 2018. 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} from '@loopback/context';
+import {urlencoded} from 'body-parser';
+import {is} from 'type-is';
+import {RestBindings} from '../keys';
+import {Request, RequestBodyParserOptions} from '../types';
+import {
+  BodyParserMiddleware,
+  getParserOptions,
+  invokeBodyParserMiddleware,
+  builtinParsers,
+} from './body-parser.helpers';
+import {BodyParser, RequestBody} from './types';
+
+export class UrlEncodedBodyParser implements BodyParser {
+  name = builtinParsers.urlencoded;
+  private urlencodedParser: BodyParserMiddleware;
+
+  constructor(
+    @inject(RestBindings.REQUEST_BODY_PARSER_OPTIONS, {optional: true})
+    options: RequestBodyParserOptions = {},
+  ) {
+    const urlencodedOptions = getParserOptions('urlencoded', options);
+    this.urlencodedParser = urlencoded(urlencodedOptions);
+  }
+
+  supports(mediaType: string) {
+    return !!is(mediaType, 'urlencoded');
+  }
+
+  async parse(request: Request): Promise<RequestBody> {
+    const body = await invokeBodyParserMiddleware(
+      this.urlencodedParser,
+      request,
+    );
+    return {value: body, coercionRequired: true};
+  }
+}

package/src/body-parsers/index.ts

@@ -0,0 +1,13 @@
+// Copyright IBM Corp. 2018. 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 './body-parser';
+export * from './body-parser.helpers';
+export * from './body-parser.json';
+export * from './body-parser.raw';
+export * from './body-parser.stream';
+export * from './body-parser.text';
+export * from './body-parser.urlencoded';
+export * from './types';

package/src/body-parsers/types.ts

@@ -0,0 +1,60 @@
+// 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 {ReferenceObject, SchemaObject} from '@loopback/openapi-v3';
+import {Request} from '../types';
+/**
+ * Request body with metadata
+ */
+export type RequestBody = {
+  /**
+   * Parsed value of the request body
+   */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  value: any | undefined;
+  /**
+   * Is coercion required? Some forms of request such as urlencoded don't
+   * have rich types such as number or boolean.
+   */
+  coercionRequired?: boolean;
+  /**
+   * Resolved media type
+   */
+  mediaType?: string;
+  /**
+   * Corresponding schema for the request body
+   */
+  schema?: SchemaObject | ReferenceObject;
+};
+
+/**
+ * Interface to be implemented by body parser extensions
+ */
+export interface BodyParser {
+  /**
+   * Name of the parser
+   */
+  name: string | symbol;
+  /**
+   * Indicate if the given media type is supported
+   * @param mediaType - Media type
+   */
+  supports(mediaType: string): boolean;
+  /**
+   * Parse the request body
+   * @param request - http request
+   */
+  parse(request: Request): Promise<RequestBody>;
+}
+
+/**
+ * Plain function for body parsing
+ */
+export type BodyParserFunction = (request: Request) => Promise<RequestBody>;
+
+/**
+ * Binding tag for request body parser extensions
+ */
+export const REQUEST_BODY_PARSER_TAG = 'rest.requestBodyParser';

package/src/coercion/coerce-parameter.ts

@@ -0,0 +1,207 @@
+// 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 {isReferenceObject, ParameterObject} from '@loopback/openapi-v3';
+import debugModule from 'debug';
+import {RestHttpErrors} from '../';
+import {parseJson} from '../parse-json';
+import {
+  DateCoercionOptions,
+  getOAIPrimitiveType,
+  IntegerCoercionOptions,
+  isEmpty,
+  isFalse,
+  isTrue,
+  isValidDateTime,
+  matchDateFormat,
+} from './utils';
+import {Validator} from './validator';
+const isRFC3339 = require('validator/lib/isRFC3339');
+const debug = debugModule('loopback:rest:coercion');
+
+/**
+ * Coerce the http raw data to a JavaScript type data of a parameter
+ * according to its OpenAPI schema specification.
+ *
+ * @param data - The raw data get from http request
+ * @param schema - The parameter's schema defined in OpenAPI specification
+ */
+export function coerceParameter(
+  data: string | undefined | object,
+  spec: ParameterObject,
+) {
+  let schema = spec.schema;
+
+  // If a query parameter is a url encoded Json object, the schema is defined under content['application/json']
+  if (!schema && spec.in === 'query' && spec.content) {
+    const jsonSpec = spec.content['application/json'];
+    schema = jsonSpec.schema;
+  }
+
+  if (!schema || isReferenceObject(schema)) {
+    debug(
+      'The parameter with schema %s is not coerced since schema' +
+        'dereference is not supported yet.',
+      schema,
+    );
+    return data;
+  }
+  const OAIType = getOAIPrimitiveType(schema.type, schema.format);
+  const validator = new Validator({parameterSpec: spec});
+
+  validator.validateParamBeforeCoercion(data);
+  if (data === undefined) return data;
+
+  switch (OAIType) {
+    case 'byte':
+      return coerceBuffer(data, spec);
+    case 'date':
+      return coerceDatetime(data, spec, {dateOnly: true});
+    case 'date-time':
+      return coerceDatetime(data, spec);
+    case 'float':
+    case 'double':
+    case 'number':
+      return coerceNumber(data, spec);
+    case 'long':
+      return coerceInteger(data, spec, {isLong: true});
+    case 'integer':
+      return coerceInteger(data, spec);
+    case 'boolean':
+      return coerceBoolean(data, spec);
+    case 'object':
+      return coerceObject(data, spec);
+    case 'string':
+    case 'password':
+      return coerceString(data, spec);
+    default:
+      return data;
+  }
+}
+
+function coerceString(data: string | object, spec: ParameterObject) {
+  if (typeof data !== 'string')
+    throw RestHttpErrors.invalidData(data, spec.name);
+
+  debug('data of type string is coerced to %s', data);
+  return data;
+}
+
+function coerceBuffer(data: string | object, spec: ParameterObject) {
+  if (typeof data === 'object')
+    throw RestHttpErrors.invalidData(data, spec.name);
+  return Buffer.from(data, 'base64');
+}
+
+function coerceDatetime(
+  data: string | object,
+  spec: ParameterObject,
+  options?: DateCoercionOptions,
+) {
+  if (typeof data === 'object' || isEmpty(data))
+    throw RestHttpErrors.invalidData(data, spec.name);
+
+  if (options?.dateOnly) {
+    if (!matchDateFormat(data))
+      throw RestHttpErrors.invalidData(data, spec.name);
+  } else {
+    if (!isRFC3339(data)) throw RestHttpErrors.invalidData(data, spec.name);
+  }
+
+  const coercedDate = new Date(data);
+  if (!isValidDateTime(coercedDate))
+    throw RestHttpErrors.invalidData(data, spec.name);
+  return coercedDate;
+}
+
+function coerceNumber(data: string | object, spec: ParameterObject) {
+  if (typeof data === 'object' || isEmpty(data))
+    throw RestHttpErrors.invalidData(data, spec.name);
+
+  const coercedNum = Number(data);
+  if (isNaN(coercedNum)) throw RestHttpErrors.invalidData(data, spec.name);
+
+  debug('data of type number is coerced to %s', coercedNum);
+  return coercedNum;
+}
+
+function coerceInteger(
+  data: string | object,
+  spec: ParameterObject,
+  options?: IntegerCoercionOptions,
+) {
+  if (typeof data === 'object' || isEmpty(data))
+    throw RestHttpErrors.invalidData(data, spec.name);
+
+  const coercedInt = Number(data);
+  if (isNaN(coercedInt!)) throw RestHttpErrors.invalidData(data, spec.name);
+
+  if (options?.isLong) {
+    if (!Number.isInteger(coercedInt))
+      throw RestHttpErrors.invalidData(data, spec.name);
+  } else {
+    if (!Number.isSafeInteger(coercedInt))
+      throw RestHttpErrors.invalidData(data, spec.name);
+  }
+
+  debug('data of type integer is coerced to %s', coercedInt);
+  return coercedInt;
+}
+
+function coerceBoolean(data: string | object, spec: ParameterObject) {
+  if (typeof data === 'object' || isEmpty(data))
+    throw RestHttpErrors.invalidData(data, spec.name);
+  if (isTrue(data)) return true;
+  if (isFalse(data)) return false;
+  throw RestHttpErrors.invalidData(data, spec.name);
+}
+
+function coerceObject(input: string | object, spec: ParameterObject) {
+  const data = parseJsonIfNeeded(input, spec);
+
+  if (data === undefined) {
+    // Skip any further checks and coercions, nothing we can do with `undefined`
+    return undefined;
+  }
+
+  if (typeof data !== 'object' || Array.isArray(data))
+    throw RestHttpErrors.invalidData(input, spec.name);
+
+  // TODO(bajtos) apply coercion based on properties defined by spec.schema
+  return data;
+}
+
+function parseJsonIfNeeded(
+  data: string | object,
+  spec: ParameterObject,
+): string | object | undefined {
+  if (typeof data !== 'string') return data;
+
+  if (spec.in !== 'query' || (spec.in === 'query' && !spec.content)) {
+    debug(
+      'Skipping JSON.parse, argument %s is not a url encoded json object query parameter (since content field is missing in parameter schema)',
+      spec.name,
+    );
+    return data;
+  }
+
+  if (data === '') {
+    debug('Converted empty string to object value `undefined`');
+    return undefined;
+  }
+
+  try {
+    const result = parseJson(data);
+    debug('Parsed parameter %s as %j', spec.name, result);
+    return result;
+  } catch (err) {
+    debug('Cannot parse %s value %j as JSON: %s', spec.name, data, err.message);
+    throw RestHttpErrors.invalidData(data, spec.name, {
+      details: {
+        syntaxError: err.message,
+      },
+    });
+  }
+}

package/src/coercion/utils.ts

@@ -0,0 +1,103 @@
+// 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 debugModule from 'debug';
+const debug = debugModule('loopback:rest:coercion');
+
+/**
+ * Options for function coerceDatetime
+ */
+export type DateCoercionOptions = {
+  dateOnly?: boolean;
+};
+
+/**
+ * Options for function coerceInteger
+ */
+export type IntegerCoercionOptions = {
+  isLong?: boolean;
+};
+
+export function isEmpty(data: string) {
+  const result = data === '';
+  debug('isEmpty(%j) -> %s', data, result);
+  return result;
+}
+/**
+ * A set of truthy values. A data in this set will be coerced to `true`.
+ *
+ * @param data - The raw data get from http request
+ * @returns The corresponding coerced boolean type
+ */
+export function isTrue(data: string): boolean {
+  return ['TRUE', '1'].includes(data.toUpperCase());
+}
+
+/**
+ * A set of falsy values. A data in this set will be coerced to `false`.
+ * @param data - The raw data get from http request
+ * @returns The corresponding coerced boolean type
+ */
+export function isFalse(data: string): boolean {
+  return ['FALSE', '0'].includes(data.toUpperCase());
+}
+
+/**
+ * Return false for invalid date
+ */
+export function isValidDateTime(data: Date) {
+  return isNaN(data.getTime()) ? false : true;
+}
+
+const REGEX_RFC3339_DATE = /^(-?(?:[1-9][0-9]*)?[0-9]{4})-(1[0-2]|0[1-9])-(3[01]|0[1-9]|[12][0-9])$/;
+
+/**
+ * Return true when a date follows the RFC3339 standard
+ *
+ * @param date - The date to verify
+ */
+export function matchDateFormat(date: string) {
+  const pattern = new RegExp(REGEX_RFC3339_DATE);
+  const result = pattern.test(date);
+  debug('matchDateFormat(%j) -> %s', date, result);
+  return result;
+}
+
+/**
+ * Return the corresponding OpenAPI data type given an OpenAPI schema
+ *
+ * @param type - The type in an OpenAPI schema specification
+ * @param format - The format in an OpenAPI schema specification
+ */
+export function getOAIPrimitiveType(type?: string, format?: string) {
+  if (type === 'object' || type === 'array') return type;
+  if (type === 'string') {
+    switch (format) {
+      case 'byte':
+        return 'byte';
+      case 'binary':
+        return 'binary';
+      case 'date':
+        return 'date';
+      case 'date-time':
+        return 'date-time';
+      case 'password':
+        return 'password';
+      default:
+        return 'string';
+    }
+  }
+  if (type === 'boolean') return 'boolean';
+  if (type === 'number')
+    switch (format) {
+      case 'float':
+        return 'float';
+      case 'double':
+        return 'double';
+      default:
+        return 'number';
+    }
+  if (type === 'integer') return format === 'int64' ? 'long' : 'integer';
+}