Service Locks Microservice for Node.js / ES2017 V2

Distributed locks microservice for Pip.Services in Node.js

Quick Links

• Download
• Develop
• Configure
• Run
• Use
• Acknowledgements
• Source Documentation

Download

Right now the only way to get the microservice is to check it out directly from github repository:

git clone [email protected]/entinco/eic-services-infrastructure2/src/master/service-locks2-node.git

Pip.Controller team is working to implement packaging and make stable releases available as zip downloadable archives.

Develop

This document provides high-level instructions on how to build and test the microservice.

Environment Setup

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

After node is installed you can check it by running the following command:

node -version

Then you need to configure node tools:

# Install typescript compiler
npm install typescript -g

# Install mocha test runner
npm install mocha -g

To work with GitHub code repository you need to install Git from: 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:

• Download and install MongoDB database from https://www.mongodb.org/downloads

Installing

After your environment is ready you can check out microservice source code from the Github repository:

git clone [email protected]/entinco/eic-services-infrastructure2/src/master/service-locks2-node.git

Then go to the project folder and install dependent modules:

# Install dependencies
npm install

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

# Update source code updates from github
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 to github. The process will output compiled javascript files into /bin folder.

tsc

When you do continuous edit-build-test cycle, you can run typescript compiler with --watch option to detect and compile changes you make automatically:

tsc --watch

Testing

Before you execute tests you need to set configuration options in config.yml file.

Command to run unit tests:

npm test

You can also execute benchmarks as:

npm run benchmark

Contributing

Developers interested in contributing should read the following instructions:

• How to Contribute
• Guidelines
• Styleguide
• ChangeLog

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

Configure

Cluster microservice configuration structure follows the standard configuration structure.

Persistence

The microservice supports three types of persistence: in-memory, flat files or MongoDB. In-memory and flat files are great for development and testing, while MongoDB is a good option with outstanding performance and scalability, suitable for demanding production installations. You can choose and configure the option that suits your needs.

For more information on this section read Pip.Controllers Configuration Guide

Memory

Memory persistence has the following configuration properties:

• options: object - Misc configuration options
  • max_page_size: number - Maximum number of items per page (default: 100)

Example:

- descriptor: "service-locks:persistence:memory:default:1.0"
  options:
    max_page_size: 100

File

Flat file persistence has the following configuration properties:

• path: string - file path where SystemEventV1 objects are stored. The object are written into the file in JSON format.
• options: object - Misc configuration options
  • max_page_size: number - Maximum number of items per page (default: 100)

Example:

- descriptor: "service-locks:persistence:file:default:1.0"
  path: "./data/locks"

MongoDB

MongoDB persistence has the following configuration properties:

• connection(s): object - MongoDB connection properties
• options: object - (optional) MongoDB connection options. See: https://www.mongodb.com/docs/drivers/node/current/fundamentals/connection/ for more details.
• debug: boolean - (optional) Enables or disables connection debugging

Example:

- descriptor: "service-locks:persistence:mongodb:default:1.0"
  collection: "locks"
  connection:
    uri: "mongodb://localhost/pipservicestest"
    host: "localhost"
    port: 27017
    database: "app"
  credential:
    username: "user_db"
    password: "passwd_db"

Service

The service component contains the core business logic of the microservice. Component has the following configuration properties:

• release_own_locks_only: boolean - if the parameter is set to true, it is allowed to release only own locks
• release_admin_id: string - client id that allows to release other clients locks despite the specified parameter release_own_locks_only
• clean_interval: 60000 - interval between call garbage collector for delete expired locks, if clean_interval=0 GC is stopped

Example:

- descriptor: "service-locks:service:default:default:1.0"
  options:
    release_own_locks_only: true
    release_admin_id: "12345"

Controllers

The controller components (also called endpoints) expose external microservice API for the consumers. Each microservice can expose multiple APIs (HTTP/REST) and multiple versions of the same API type. At least one service 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 is 'http')
  • host: string - IP address/hostname binding (default is '0.0.0.0')
  • port: number - HTTP port number

Example:

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

For more information on this section read Pip.Controllers Configuration Guide

Run

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 microservices by following instructions in the Download section.

Step 2. Add config.json file to the config folder and set configuration parameters. See Configure section for details.

Step 3. Start the microservice using the command:

node ./bin/main.js

Use

This section describes the microservice API contract and provides usage examples.

Contract

Data objects used by this microservice:

LockV1

• id: string - lock id
• client_id: string - client id
• created: Date - creation time
• expire_time: Date - expiration time

Acknowledgements

This microservice was created and currently maintained by:

• Sergey Seroukhov
• Denis Kuznetsov
• Danylo Kuznetsov