service-msgdistribution2-node

v1.0.0

Published

a year ago

Message distribution microservice in Node.js / ES2017 V2

0High
0Medium
0Low

pipdeveloper

pip.services message distribution email sms microservice

Message Distribution Microservice for Node.js / ES2017 V2

This is a message distribution management microservice from the Pip.Services library.

Distributes messages to one or many recipients using their configured delivery methods: email or SMS.

The microservice currently supports the following deployment options:

Deployment platforms: Standalone process, AWS Lambda function
External APIs: HTTP/REST, gRPC

This microservice has optional dependencies on the following microservices:

service-email2-node - to send email messages
service-emailsettings2-node - to get recipient email settings
service-msgtemplates2-node - to get message templates
service-sms2-node - to send SMS messages
service-smssettings2-node - to get recipient SMS settings

Contract

The logical contract of the microservice is presented below. For physical implementation (HTTP/REST, gRPC, Lambda), please refer to the documentation of the specific protocol.

class MessageV1 {
    public template?: string;
    public from?: string;
    public cc?: string;
    public bcc?: string;
    public reply_to?: string;
    public subject?: any;
    public text?: any;
    public html?: any;
}

interface IMessageDistributionService {
    sendMessage(ctx: IContext, recipient: RecipientV1,
        message: MessageV1, parameters: ConfigParams, method: string): Promise<void>;
    
    sendMessages(ctx: IContext, recipients: RecipientV1[],
        message: MessageV1, parameters: ConfigParams, method: string): Promise<void>;

    sendMessageToRecipient(ctx: IContext, recipientId: string, subscription: string,
        message: MessageV1, parameters: ConfigParams, method: string): Promise<void>;
    
    sendMessageToRecipients(ctx: IContext, recipientIds: string[], subscription: string,
        message: MessageV1, parameters: ConfigParams, method: string): Promise<void>;
}

Messages can be defined directly or loaded from a message template (stored in the msgtemplates2 service).

When a message is set directly to its subject, the text and HTML content can be set by a handlebars template, that is processed using set parameters. Here is an example:

Dear {{ name }},
<p>
Please verify your email address. Your verification code is {{ code }}.
</p>
<p>
Click on the 
<a href="{{ clientUrl }}/#/verify_email?server_url={{ serverUrl }}&email={{ email }}&code={{ code }}">link</a>
to complete the verification procedure.
</p>
---<br/>
{{ signature }}

Download

The main way to get the microservice is to check it out directly from the Bitbucket repository:

git clone [email protected]:entinco/eic-services-users2.git

The microservice is also available as a NPM package under the same name. You can add a dependency to the microservice into the package.json file of your project:

{
    ...
    "dependencies": {
        ...
        "service-msgdistribution2-node": "^1.0.*",
        ...
    }
}

Develop

Environment Setup

This is a Node.js project and you have to install Node.js tools. You can download them from the official Node.js website: https://nodejs.org/en/download/

After Node.js is installed, you can verify its version:

node --version

Then you need to install some node tools (recommended to be global):

# Install typescript compiler
npm install typescript -g
 
# Install mocha test runner
npm install mocha -g

To work with the code repository, you need to install Git: https://git-scm.com/downloads

If you are planning to develop and test using persistent storages other than flat files, you may need to install database servers:

Install MongoDB: https://www.mongodb.org/downloads

Installing

After your environment is ready, you can copy the microservice source code from the repository:

git clone [email protected]:entinco/eic-services-users2.git

Then go to the project folder and install dependent modules:

# Install dependencies
npm install

If you have worked with the microservice before, you can check out the latest changes and update the dependencies:

# Update source code
git pull

# Update dependencies
npm update

Building

This microservice is written in TypeScript language which is transcompiled into JavaScript. So, if you make changes to the source code, you need to compile it before running or committing. The process will output compiled JavaScript files into the "obj" folder:

tsc

When you do continuous edit-build-test cycles, you can run the TypeScript compiler with "--watch" to detect and compile changes you make automatically:

tsc --watch

Testing

Before you execute tests, you may need to set configuration options into a config.yml file, located by default in the "config" folder in the root of the project. For more information, see the Configure guide.

Run unit tests:

npm test

Execute benchmarks:

npm run benchmark

Contributing

Developers interested in contributing should read the following instructions:

Please do not ask general questions in an issue. Issues are only to report bugs, request enhancements, or request new features. For general questions and discussions, use the Contributors Forum.

It is important to note that for each release, the Changelog is a resource that will itemize all:

Bug Fixes
New Features
Breaking Changes

Run

Add config.yml file to the root of the microservice folder and set configuration parameters. As the starting point you can use example configuration from config.example.yml file. Example of microservice configuration

---
- descriptor: "service-commons:logger:console:default:1.0"
  level: "trace"

- descriptor: "service-msgdistribution:controller:default:default:1.0"
  
- descriptor: "service-msgdistribution:service:commandable-http:default:1.0"
  connection:
    protocol: "http"
    host: "0.0.0.0"
    port: 8080

For more information on the microservice configuration see Configuration Guide.

Start the microservice using the command:

node run

Configure

As a starting point, you can use this example to create your own config.yml file:

---
- descriptor: "pip-services:context-info:default:default:1.0"
  name: "service-msgdistribution2"
  description: "Message distribution microservice for pip-services V2"

- descriptor: "pip-services:logger:console:default:1.0"
  level: "trace"

- descriptor: "msgdistribution:service:default:default:1.0"

- descriptor: "pip-services:endpoint:http:default:1.0"
  connection:
    protocol: "http"
    host: "0.0.0.0"
    port: 8080

- descriptor: "msgdistribution:controller:commandable-http:default:1.0"

Afterwards, check all configuration options. Specifically, pay attention to connection options for database and dependent microservices.

For more information on this section, read the Pip.Services Configuration Guide.

Service

Service has the following configuration properties:

template_params: object - (optional) Message template parameters.
- server_url string - (optional) URL to use for retrieving message templates (default: 'http://localhost:8080')

Example:

- descriptor: "msgdistribution:service:default:default:1.0"
  template_params:
    server_url: "http://localhost:8080"

Controllers

The controller components (also called "endpoints") expose external microservice API for consumers. Each microservice can expose multiple APIs (HTTP/REST, gRPC) and multiple versions of the same API type. At least one controller is required for the microservice to run successfully.

HTTP

HTTP/REST controller has the following configuration properties:

connection: object - HTTP transport configuration options
- protocol: string - HTTP protocol - 'http' or 'https' (default: 'http')
- host: string - IP address/hostname binding (default: '0.0.0.0')
- port: number - HTTP port number
swagger: object - (optional) Swagger controller integration options
- enable: boolean - (optional) Enables or disables Swagger integration
- auto: boolean - (optional) Enables or disables automatic Swagger integration configuration

Example:

# Common HTTP endpoint
- descriptor: "pip-services:endpoint:http:default:1.0"
  connection:
    protocol: "http"
    host: "0.0.0.0"
    port: 8080

# HTTP controller
- descriptor: "msgdistribution:controller:commandable-http:default:1.0"
  swagger:
    enable: true
    auto: true

gRPC

gRPC controller has the following configuration properties:

connection: object - gRPC transport configuration options
- protocol: string - gRPC protocol - 'http' or 'https' (default: 'http')
- host: string - IP address/hostname binding (default: '0.0.0.0')
- port: number - gRPC port number

Example:

# Common GRPC endpoint
- descriptor: "pip-services:endpoint:grpc:default:1.0"
  connection:
    protocol: "http"
    host: "0.0.0.0"
    port: 8090

# GRPC controller
- descriptor: "msgdistribution:controller:grpc:default:1.0"

# Commandable GRPC controller
- descriptor: "msgdistribution:controller:commandable-grpc:default:1.0"

For more information on this section, read the Pip.Services Configuration Guide.

Run

Standalone Process

The simplest way to deploy the microservice is to run it as a standalone process. This microservice is implemented in JavaScript and requires installation of Node.js. You can get it from the official site at https://nodejs.org/en/download

Step 1. Download the microservice by following the Download instructions.

Step 2. Add a config.yml file to the "config" folder in the root of the project and set configuration parameters. See the Configure guide for details.

Step 3. Start the microservice:

node ./bin/main.js

AWS Lambda Function

This microservice can also be packaged and deployed to AWS as a Lambda function. This microservice is implemented in JavaScript and requires the installation of Node.js. You can download it from the official Node.js website: https://nodejs.org/en/download/

Step 1. Download the microservice by following the Download instructions.

Step 2. Add a config.yml file to the "config" folder in the root of the project and set configuration parameters. See the Configure guide for details.

Step 3. Go to the project folder and install the dependent modules:

npm install

Step 4. Package the project folder into a .zip file:

zip -r lambda_function.zip .

Step 5. Go to the AWS Lambda console and create a new Lambda function.

Name: "service-msgdistribution2-node"
Runtime: Choose "Node.js 14.x" or newer
Function code: Upload the .zip package of the project folder

Step 6: Configure any triggers necessary to invoke the function or invoke it via the AWS Lambda console.

Use

The easiest way to work with the microservice is to use the client library. The complete list of available client libraries for different languages is listed in the Quick Links.

If you use Node.js, then you can add a dependency to the client library into the package.json file of your project:

{
    ...
    "dependencies": {
        ...
        "client-msgdistribution2-node": "^1.0.*",
        ...
    }
}

Then install the dependency:

# Install new dependencies
npm install

# Update already installed dependencies
npm update

Inside your code, get the reference to the client library:

let node_lib = new require('client-msgdistribution2-node');

Define client configuration parameters that match the configuration of the microservice external API:

// Client configuration
let config = {
    connection: {
        protocol: 'http',
        host: 'localhost', 
        port: 8080
    }
};

Instantiate the client and open a connection to the microservice:

// Create the client instance
let client = node_lib.MessageDistributionCommandableHttpClientV1(config);

// Connect to the microservice
try {
    await client.open(null);
    // Work with the microservice
    ...
}
catch (err) {
    console.error('Connection to the microservice failed');
    console.error(err);
}

Now the client is ready to perform operations:

// Send email message to a recipient
await client.sendMessageToRecipient(
    null, '123', null,
    { 
        subject: 'Test',
        text: 'This is a test message'
    },
    null, 'email',
);

Acknowledgements

This microservice was created by Sergey Seroukhov and is currently maintained by Michael Seroukhov.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

Message Distribution Microservice for Node.js / ES2017 V2

Quick Links

Contract

Download

Develop

Environment Setup

Installing

Building

Testing

Contributing

Run

Configure

Service

Controllers

HTTP

gRPC

Run

Standalone Process

AWS Lambda Function

Use

Acknowledgements