# @dojot/dojot-module

> A library that provides utilities and methods for dojot

Latest version **0.2.3** (published 2021-06-08) · Apache-2.0 license · 0 weekly downloads

## Install

```sh
npm install @dojot/dojot-module
pnpm add @dojot/dojot-module
yarn add @dojot/dojot-module
bun add @dojot/dojot-module
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.2.3 |
| Published | 2021-06-08 |
| First published | 2018-08-23 |
| Weekly downloads | 0 |
| License | Apache-2.0 |
| TypeScript types | none |
| Module format | CommonJS |
| Node | <14 |
| Dependencies | 7 |
| Unpacked size | 134.5 KB |
| Known vulnerabilities | 0 (+25 in 2 direct dependencies) |
| Install scripts | no |
| Author | Muhamed Avila |
| Maintainers | thiagodpf, manuel.gavidia, giovannicuriel, mprevide, scaraficci, timedojot |
| Keywords | dojot, iot |

## Links

- npm: https://www.npmjs.com/package/@dojot/dojot-module
- Repository: https://github.com/dojot/dojot-module-nodejs
- Homepage: https://github.com/dojot/dojot-module-nodejs/#readme
- Issues: https://github.com/dojot/dojot-module-nodejs/issues
- npm.io page: https://npm.io/package/@dojot/dojot-module

## Dependencies (7)

- [uuid](https://npm.io/package/uuid.md) ^3.3.2
- [axios](https://npm.io/package/axios.md) ^0.18.0
- [moment](https://npm.io/package/moment.md) ^2.22.2
- [express](https://npm.io/package/express.md) ^4.16.3
- [node-rdkafka](https://npm.io/package/node-rdkafka.md) 2.9.1
- [keycloak-admin](https://npm.io/package/keycloak-admin.md) 1.14.12
- [@dojot/dojot-module-logger](https://npm.io/package/@dojot/dojot-module-logger.md) ^0.1.0

## Recent versions

- 0.2.3 (latest) — 2021-06-08
- 0.2.2 — 2021-05-27
- 0.2.1 — 2021-05-21
- 0.2.0 — 2021-05-03
- 0.1.2 — 2021-02-25
- 0.1.1 — 2020-12-07
- 0.1.0 — 2020-12-07
- 0.0.1-beta.9 — 2020-09-28
- 0.0.1-beta.8 — 2020-01-21
- 0.0.1-beta.7 — 2019-10-29
- 0.0.1-beta.6 — 2019-08-23
- 0.0.1-beta.5 — 2019-05-30
- 0.0.1-beta.4 — 2019-03-20
- 0.0.1-beta.3 — 2019-01-31
- 0.0.1-beta.2 — 2019-01-31
- … 8 more at https://npm.io/package/@dojot/dojot-module/versions

## README

# dojot-module

[![CodeFactor](https://www.codefactor.io/repository/github/dojot/dojot-module-nodejs/badge)](https://www.codefactor.io/repository/github/dojot/dojot-module-nodejs)
[![DeepScan grade](https://deepscan.io/api/teams/2690/projects/3914/branches/33256/badge/grade.svg)](https://deepscan.io/dashboard#view=project&tid=2690&pid=3914&bid=33256)
[![codecov](https://codecov.io/gh/dojot/dojot-module-nodejs/branch/master/graph/badge.svg)](https://codecov.io/gh/dojot/dojot-module-nodejs)
[![npm version](https://badge.fury.io/js/%40dojot%2Fdojot-module.svg)](https://badge.fury.io/js/%40dojot%2Fdojot-module)

Common library to be used in dojot modules.

**Attention**: As of version v0.2, this library no longer has integration with the old "auth" service, but with the "keycloak" service.
Be aware that the environment variables `KEYCLOAK_USER` and `KEYCLOAK_PASSWORD` will probably have to be passed to services that use this library. This user should be able to get the existing realm lists from keycloak.

## Overview

This library is intended to handle all the necessary operations that a service
needs to perform in order to communicate with other dojot services. These
operations are:

- Sending and receiving messages via Kafka;
- Subscribing to new Kafka topics whenever a new tenant is created;

Thus, the service should only inform the library of which subjects it is
interested in and how the messages should be processed.

## How to install

Installing this package is no different than any other from npm. Just execute:

```bash

npm install @dojot/dojot-module

```

which will install this module in its latest version.

## How to use

Using it is also very easy. All normal operations involve using the Messenger
class, which is responsible for communicating with the message broker (Kafka)
and generating events to any component interested in such messages. Also, it
provides a very simple mechanism of event generation and subscription so that
a library could use it to generate more specific events based on those messages.
More on that later.

The folowing code is an example of a code that simply prints any message that
it receives from a particular subject.


```javascript
"use strict";
var dojot = require("@dojot/dojot-module");
var logger = require("@dojot/dojot-module-logger").logger;

var config = dojot.Config;
var messenger = new dojot.Messenger("dojot-snoop", config);
messenger.init();

// Create a channel using a default subject "device-data"
// These "communication channels" will handle all the tenant processing and
// message receival, so that the service implementation would only set the
// message processing callback (done by 'messenger.on' calls).
//
// Creating a new channel will inform the library that the service is interested
// in read/write messages to a particular subject.
messenger.createChannel(config.dojot.subjects.deviceData, "rw");

// Create a channel using a particular subject "service-status"
messenger.createChannel("service-status", "w");

// Register callback to process incoming device data
messenger.on(config.dojot.subjects.deviceData, "message", (tenant, message, extraInfo) => {
  logger.info(`Client: Received message in device data subject.`);
  logger.info(`Client: Tenant is: ${tenant}`);
  logger.info(`Client: Message is: ${message}`);
  logger.info(`Client: ExtraInfo is: ${extraInfo}`);
});

// Publish a message on "service-status" subject using "dojot-management" tenant
messenger.publish("service-status", config.management.tenant, "service X is up");

```

## Configuration

This library might be configured in different ways. Each class (Messenger,
Consumer and Producer) receives a configuration object in its constructor. It
should have the following attributes at least:

```json
{
  "kafka": {
    "producer": {
      "metadata.brokers.list": "kafka:9092",
      "socket.keepalive.enable": true,
      "dr_cb": true
    },
    "consumer": {
      "group.id": "sample-group",
      "metadata.brokers.list": "kafka:9092",
    }
  },
  "databroker": {
    "url": "http://data-broker",
    "timeoutSleep": 2,
    "connectionRetries": 5,
  },
  "keycloak": {
      "basePath": "http://keycloak:8080/auth",
      "timeoutSleep": 5,
      "connectionRetries": 5,
      "ignoreRealm": "master",
      "credentials": {
        "username": "admin",
        "password": "admin",
        "grantType": "password",
        "clientId":  "admin-cli",
      }
    },
  "deviceManager": {
    "url": "http://device-manager:5000",
    "timeoutSleep": 5,
    "connectionRetries": 3,
  },
  "dojot": {
    "management": {
      "user": "dojot-management",
      "tenant": "dojot-management"
    },
    "subjects": {
      "tenancy": "dojot.tenancy",
      "devices": "dojot.device-manager.device",
      "deviceData": "device-data",
    }
  }
}
```

All these parameters can be found in [config.js](./lib/config.js) file. It is
recommended that the service implementation use this file as basis to configure
other classes.

The Kafka section follows the parameters used by
[node-rdkafka](https://github.com/Blizzard/node-rdkafka) library, which in turn
follows the configuration of
[librdkafka](https://github.com/edenhill/librdkafka). These are the bare
minumum that this library needs in order to operate correctly. All the values
are the default ones, they might be changed depending on deployment scenario.

The config.js file will also get a few environment variables in order to ease
configuration. They are:

```bash
export KAFKA_HOSTS = "kafka:9092"
export KAFKA_GROUP_ID = "dojot-module"
export DATA_BROKER_URL = "http://data-broker"
export KEYCLOAK_URL = "http://keycloak:8080/auth"
export KEYCLOAK_USER = "admin"
export KEYCLOAK_PASSWORD = "admin"
export DEVICE_MANAGER_URL = "http://device-manager:5000"
export DOJOT_MANAGEMENT_USER = "dojot-management"
export DOJOT_MANAGEMENT_TENANT = "dojot-management"
export DOJOT_SUBJECT_TENANCY = "dojot.tenancy"
export DOJOT_SUBJECT_DEVICES = "dojot.device-manager.device"
export DOJOT_SUBJECT_DEVICE_DATA = "device-data"
```

# **License**

The dojot-module-nodejs source code is released under Apache License 2.0.

Check NOTICE and LICENSE files for more information.

---
_Source: https://npm.io/package/@dojot/dojot-module · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._