feat(rest): add msgpack body parser

Signed-off-by: Rifa Achrinza <[email protected]>

.gitignore

@@ -11,6 +11,7 @@ fixtures/tsdocs-monorepo/packages/pkg1/docs
 acceptance/*/dist
 packages/*/dist
 extensions/*/dist
+bodyparsers/*/dist
 examples/*/dist
 benchmark/dist
 **/package

CODEOWNERS

@@ -324,6 +324,14 @@
 /extensions/graphql @raymondfeng
 /examples/graphql @raymondfeng
 
+#
+# MessagePack body parser
+#
+# - Issue label: n/a
+# - Primary owner(s): @achrinza
+# - Standby owner(s): n/a
+/bodyparsers/rest-msgpack @achrinza
+
 #
 # Build & internal tooling
 #

bodyparsers/rest-msgpack/.npmrc

@@ -0,0 +1,2 @@
+package-lock=true
+scripts-prepend-node-path=true

bodyparsers/rest-msgpack/LICENSE

@@ -0,0 +1,27 @@
+Copyright (c) IBM Corp. 2020.
+Node module: @loopback/bodyparser-msgpack
+This project is licensed under the MIT License, full text below.
+
+--------
+
+MIT License
+
+MIT License Copyright (c) IBM Corp. 2020
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice (including the next
+paragraph) shall be included in all copies or substantial portions of the
+Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

bodyparsers/rest-msgpack/README.md

@@ -0,0 +1,163 @@
+# @loopback/rest-msgpack
+
+This module extends LoopBack with the ability to receive
+[MessagePack](https://msgpack.org/) requests and transparently convert it to a
+regular JavaScript object. It provides a BodyParser implementation and a
+component to register it.
+
+## Stability: ⚠️Experimental⚠️
+
+> Experimental packages provide early access to advanced or experimental
+> functionality to get community feedback. Such modules are published to npm
+> using `0.x.y` versions. Their APIs and functionality may be subject to
+> breaking changes in future releases.
+
+## Installation
+
+```sh
+npm i @loopback/rest-msgpack --save
+```
+
+## Usage
+
+The component should be loaded in the constructor of your custom Application
+class.
+
+Start by importing the component class:
+
+```ts
+import {MsgPackBodyParserComponent} from '@loopback/rest-msgpack';
+```
+
+In the constructor, add the component to your application:
+
+```ts
+this.component(MsgPackBodyParserComponent);
+```
+
+The body parser will accept requests with the following MIME type
+(`Content-Type`) blobs:
+
+- `application/msgpack`
+- `application/x-msgpack`
+- `application/*+msgpack`
+
+### Accepting MessagePack Requests
+
+To accept MessagePack requests in a controller, amend the OpenAPI decorator to
+include the MIME type as a possible request body.
+
+For example, to update the Todo controller to accept MessagePack:
+
+```typescript
+import {post, getModelSchemaRef, requestBody} from '@loopback/rest';
+
+class TodoController {
+  // Omitted constructor for bevity
+
+  @post('/todos')
+  async create(
+    @requestBody({
+      content: {
+        // Change existing or append a new request body accepted MIME type
+        'application/msgpack': {
+          schema: getModelSchemaRef(Todo, {
+            title: 'NewTodo',
+            exclude: ['id'],
+          }),
+        },
+      },
+    })
+    todo: // Keep the request body object type, since the body parser transparently
+    // converts it into a JavaScript object.
+    Omit<Todo, 'id'>,
+
+    // For bevity, the function does not return anything. See
+    // 'Returning MessagePack Requests' below.
+  ): void {
+    this.todoRepository.create(todo);
+  }
+}
+```
+
+The MessagePack request payload will be transparently converted into a
+JavaScript object and validated against the JSON Schema.
+
+### Returning MessagePack Requests
+
+{% include note.html content="The body parser will not convert responses into `application/msgpack` automatically. This feature is being tracked by [#6275](https://github.com/strongloop/loopback-next/issues/6275)" %}
+
+To return MessagePack requests in a controller, amend the requestBody decorator
+to include the MIME type as a possible response and use a parser library.
+
+For example, to update the Todo controller to return in MessagePack:
+
+```ts
+// `msgpack-lite` is re-exported by `@loopback/rest-msgpack` for convenience.
+// It is recommended to bind it to context the inject it to benefit from
+// dependency injection.
+import {MsgPackBodyParserBindings, msgpack} from '@loopback/rest-msgpack';
+import {inject} from '@loopback/core';
+import {getModelSchemaRef, post, Response, RestBindings} from '@loopback/rest';
+
+class TodoController {
+  private readonly _response: Response;
+
+  constructor(
+    // Omitted other dependency injections (e.g. repository) for bevity.
+
+    // Inject the Response object to the controller
+    @inject(RestBindings.Http.RESPONSE)
+    private readonly _res: Response,
+  ) {}
+
+  @get('/todos', {
+    responses: {
+      '200': {
+        description: 'Array of Todo model instances',
+        content: {
+          // Update existing or amend new possible response
+          'application/msgpack': {
+            schema: {type: 'array', items: getModelSchemaRef(Todo)},
+          },
+        },
+      },
+    },
+  })
+  async findTodos(
+    @param.filter(Todo)
+    filter?: Filter<Todo>,
+
+    // Change function return type to Promise<void>.
+  ): Promise<void> {
+    // Internally, LoopBack 4 will try to guess and override the `Content-Type`
+    // header, even after manually setting the headers.
+    // Buffers are automatically detected as `application/octet-stream`.
+    // We can use `Response.end()` to bypass that.
+    //
+    // See: https://github.com/strongloop/loopback-next/issues/5168
+    //
+    this._res
+      .type('application/msgpack')
+      .end(msgpack.encode(this.todoRepository.find(filter)));
+  }
+}
+```
+
+## Contributions
+
+- [Guidelines](https://github.com/strongloop/loopback-next/blob/master/docs/CONTRIBUTING.md)
+- [Join the team](https://github.com/strongloop/loopback-next/issues/110)
+
+## Tests
+
+Run `npm test` from the root folder.
+
+## Contributors
+
+See
+[all contributors](https://github.com/strongloop/loopback-next/graphs/contributors).
+
+## License
+
+MIT

bodyparsers/rest-msgpack/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@loopback/rest-msgpack",
+  "version": "0.1.0",
+  "description": "Body parser to handle MessagePack requests in LoopBack 4.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "engines": {
+    "node": ">=10.16"
+  },
+  "scripts": {
+    "build": "lb-tsc",
+    "build:watch": "lb-tsc --watch",
+    "pretest": "npm run clean && npm run build",
+    "test": "lb-mocha \"dist/__tests__/**/*.js\"",
+    "clean": "lb-clean dist *.tsbuildinfo .eslintcache"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/strongloop/loopback-next.git",
+    "directory": "bodyparsers/msgpack"
+  },
+  "author": "IBM Corp.",
+  "license": "MIT",
+  "files": [
+    "README.md",
+    "dist",
+    "src",
+    "!*/__tests__"
+  ],
+  "peerDependencies": {
+    "@loopback/core": "^2.9.4",
+    "@loopback/rest": "^6.1.0"
+  },
+  "dependencies": {
+    "msgpack-lite": "0.1.26",
+    "tslib": "^2.0.0",
+    "type-is": "^1.6.18"
+  },
+  "devDependencies": {
+    "@loopback/build": "^6.2.1",
+    "@loopback/core": "^2.9.4",
+    "@loopback/rest": "^6.1.0",
+    "@loopback/testlab": "^3.2.3",
+    "@types/msgpack-lite": "0.1.7",
+    "@types/node": "^10.17.28",
+    "@types/type-is": "^1.6.3",
+    "typescript": "~4.0.2"
+  },
+  "copyright.owner": "IBM Corp.",
+  "publishConfig": {
+    "access": "public"
+  }
+}