@sap/xb-msg-mqtt-v311

Provides a protocol implementation for MQTT 3.1.1.

Table of contents

• Prerequisites
• Install
• Overview
• Getting started
• API
• Limitations

Prerequisites

Make sure to have an message broker available, e.g. RabbitMQ with enabled MQTT plugin.

Install

See also: https://www.npmjs.com/package/@sap/xb-msg-mqtt-v311

To add it to your project run:

npm i @sap/xb-msg-mqtt-v311

To generate complete API documentation run inside the library package folder

npm run doc

Overview

This library provides a messaging client for MQTT 3.1.1. A single client instance represents one connection to the broker.

Either TLS or NET socket is used, depending on defined client options. Besides plain TCP/IP also WebSocket is supported, with and without OAuth 2.0, grant flows ClientCredentialsFlow and ResourceOwnerPasswordCredentialsFlow.

The API works completely asynchronous based on callbacks, often providing also done (resolve) and failed (reject) callbacks. This means it would be simple to use Promise objects in the application even if the client library so far does not use it.

Getting started

There are test programs in the package folder ./examples:

• How to use plain API directly publisher.js and subscriber.js
• How to use unified streams producer.js and consumer.js

It shall run with defaults immediately if for example a RabbitMQ with active MQTT plugin is listening at localhost:1883 with default settings.

All examples support individual settings, e.g. to use a remote host or to try different stream settings. It can be provided with a js-file given as command line parameter. The file shall export a client option object. Defaults will still be used for undefined fields.

Run it like this if the file is stored in folder config, same level as examples.

node ./examples/producer.js ../config/my-options.js

Feel free to start testing with the following file content:

'use strict';

module.exports = {
    net: {
        host      : '127.0.0.1',
        port      : 1883
    },
    credentials: {
        user      : 'guest',
        password  : 'guest'
    },
    data: {
        payload   : Buffer.allocUnsafe(50).fill('X'),
        qos       : 1,
        topic     : 'sap/test/hello',
        maxCount  : 50000,
        logCount  : 1000
    }
};

The data section is ignored by the client, it is just used by the example programs.

API

The library provides a client class, which is able to manage one connection.

const MQTT = require('@sap/xb-msg-mqtt-v311');

...
const client = new MQTT.Client(options);
...

Client Options

Create a client instance using plain TCP:

const options = {
    net: {
        host: 'localhost',
        port: 1883
    },
    credentials: {
        user: '',
        password: ''
    },
    mqtt: {
        clientID : '',
        cleanSession : true,
        keepAlive : 30
    }
};

const client = new MQTT.Client(options);

or plain TCP with TLS connection:

const options = {
    tls: {
        host: 'localhost',
        port: 8883,
        ca: [
            fs.readFileSync('../../../truststore/cacert.pem'),
            fs.readFileSync('../../../truststore/cert.pem')
        ]
    },
    credentials: {
        user: '',
        password: ''
    }
};

const client = new MQTT.Client(options);

as well as MQTT over WebSocket (HTTP):

const options = {
    ws: {
        host: 'localhost',
        port: 80,
        path: '/'
        auth: 'webUser:webPass'
    }
    credentials: {
        user: 'mqttUser',            // used in CONNECT packet 
        password: 'mqttPass'         // used in CONNECT packet
    }
};

const client = new MQTT.Client(options);

or MQTT over WebSocket using TLS (HTTPS):

const options = {
    wss: {
        host: 'localhost',
        port: 443,
        path: '/',
        ca: [
            fs.readFileSync('../../../truststore/cacert.pem'),
            fs.readFileSync('../../../truststore/cert.pem')
        ]
    },
    credentials: {
        user: '',
        password: ''
    }
};

const client = new MQTT.Client(options);

Either 'tls' attributes, 'net' attributes, wss attributes or ws attributes must be provided. If more than one is provided the preference is as follows: preferred 'tls' then 'net' then 'wss' then finally 'ws'.

In case of WebSocket options the client will overwrite HTTP method (GET) and all web-socket relevant header fields. Everything else is given to http.request() or https.request().

It is also possible to provide connection data as URI:

const options = {
    uri: 'mqtt://user:pass@localhost:1883/?keepalive=300&clientid=abcd'
};
const client = new MQTT.Client(options);

Or using 'tls' again:

const options = {
    uri: 'mqtts://user:pass@localhost:8883?cacertfile=cacert.pem&cacertfile=cert.pem'
};
const client = new MQTT.Client(options);

Finally, also an array of URIs can be provided:

const options = {
    uri: [
        'mqtt://user11:pass11@host11:1883/?heartbeat=300',
        'mqtt://user22:pass22@host22:1884/'
    ]
};
const client = new MQTT.Client(options);

The client will start using the first URI and will try further URIs automatically in the given sequence until the connection can be established. If the client fails with all URIs then it stops and waits for another explicit call to connect. At this point an event 'disconnected' is raised.

An application that requires a permanent opened connection shall always handle the 'disconnect' event by calling client.connect() again, of course after a given delay time. Timers or other mechanisms may be used, depending on the application design. Keep in mind that NodeJS runtime does not guarantee precise timer execution, it depends on the event queue load.

Finally, URIs can also be combined with all other settings. URI data (as far as provided) will just overwrite the corresponding fields. A typical example could be the following:

const options = {
    uri: [
        'mqtt://user11:pass11@host11:1883/?keepalive=300',
        'mqtt://user22:pass22@host22:1884/?clientid=myCID'
    ]
    mqtt: {
        clientID: '',
        keepAlive: 60
    },
    istreams: {
        in1: {topic: 'a/b/c/d', qos: 1},
        in2: {topic: 'x/y/z/#', qos: 1}
    }
    ostreams: {
        out1: {topic: 'test/out1', qos: 0},
        out2: {topic: 'test/out2', qos: 2}
    }
};
const client = new MQTT.Client(options);

WebSocket connections may require the use of OAuth 2.0 as well. Relevant grant flows are: ClientCredentialsFlow and ResourceOwnerPasswordCredentialsFlow. One example is an external application, connecting to the cloud.

const options = {
    oa2: {
        endpoint: 'https://myzone.authentication.sap.hana.ondemand.com/oauth/token',
        client: 'myclientid',
        secret: 'myclientsecret',
    },
    wss: {
        host: 'myapp.cfapps.sap.hana.ondemand.com',
        port: 443,
        path: '/'
    }
};

const client = new MQTT.Client(options);

After an connection has been established the application may start to publish and/or subscribe. Details can be found in the sample applications, in project folder ./examples.

Message Payload

The application may provide message payload as follows:

• a simple Buffer object,
• an Array of simple Buffer objects or
• a Payload (see API) object, mainly for compatibility with other @sap/xb-msg* libraries.

After the payload was handed over to the client the buffer content must not be modified by the application. And as soon as the buffer size exceeds options.tune.ostreamPayloadCopyLimit (default 1024 bytes, minimum 128 bytes) the client will not copy these data, but will directly push it to the network socket.

Limitations

Currently, you may only set the MQTT flag cleanSession to true.