Custom Plugin Node Library

The Mia-Platform Plugin Node Library

This library is intented to ease the creation of new services to deploy on Mia-Platform.
Is highly copled with lc39 and on Fastify.

Getting Started

Install

To install the package you can run:

npm install @mia-platform/custom-plugin-lib --save

Examples

Defining a new service that integrate with the platform is as simple as in this example.
Please see also a more advanced example to see how to require more environment variables, and to specify schema definitions for validation and swagger documentation.

For using one of the two example provided you can move to one of the two directories and run:

npm run start:local

This command will launch the service on localhost:3000 with the environment variables defined in this file. Now you can consult the swagger documentation of the service at this address.

Local Development

To develop the service locally you need:

• Node 8+

To setup node, please if possible try to use nvm, so you can manage multiple versions easily. Once you have installed nvm, you can go inside the directory of the project and simply run nvm install, the .nvmrc file will install and select the correct version if you don’t already have it.

Once you have all the dependency in place, you can launch:

npm i
npm run coverage

This two commands, will install the dependencies and run the tests with the coverage report that you can view as an HTML page in coverage/lcov-report/index.html.

rawCustomPlugin

Defining a custom plugin that uses the platform’s services is as simple as in this helloWorld example. This library exports a function that optionally takes a schema of the required environment variables (you can find the reference here). This function returns a customService function, that expects an async function to initialize and configure the service (provided as the only argument). This service is a fastify instance, that also contains the method addRawCustomPlugin, that allows you to add a route. Multiple routes can be added in this way.
For each route you have to specify an async handler. You should always return something (strings, objects, streams), unless you set the response status code to 204. Please read here for further information about async handlers.
You must also specify the http method, and the path of the hander. Optionally you can indicate the JSONSchemas to validate the querystring, the parameters, the payload, the response.
In addition to validation, you will also have a swagger documentation available at the /documentation/ path.

Thanks to TypeScript's type definitions, editors can actually provide autocompletion for the additional methods of the request object such as getUserId or getGroups.

In the async initialization function you can also access the fastify instance, so you can register any plugin, see here for a list of currently available plugins.
In addition, you can register additional content-type parsers.

NB: the fifth parameter of rawCustomPlugin should be used wisely. See tests for that.

Testing

CustomPlugin expose getDirectServiceProxy and getServiceProxy for testing purpose:

getDirectServiceProxy

Import the function in you test:

const { getDirectServiceProxy } = require('@mia-platform/custom-plugin-lib') 
const myServiceProxy = getDirectServiceProxy(MY_SERVICE_NAME)

all the options accepted by the getDirectServiceProxy can be passed (es: { port: CUSTOM_PORT }).

getServiceProxy

It need the MICROSERVICE_GATEWAY_SERVICE_NAME so you need to pass it like this:

const { getServiceProxy } = require('@mia-platform/custom-plugin-lib')
const myServiceProxy = getServiceProxy(MICROSERVICE_GATEWAY_SERVICE_NAME)

Configuration

To use the library, you should specify the environment variables listed here, other variables can be specified by setting your envSchema when calling the plugin.