var client = new MqttReqRes({
brokerProtocol: 'mqtt',
brokerHostname: '127.0.0.1',
brokerPort: 9999,
clientId: 'client-a'
})
request(toClientId[, payload, meta])
send a request to an other client.
toClientId string, required. the receiver's client id
payload string|object|Buffer, optional. the message string or object to be sent. for Buffer type see Node docs
meta object, optional. an object to be sent additionaly.
returns Promise which resolves to object response
Example:
clientA.request('client-b', 'hello!', {foo: 'bar'})
.then(function (response) {
/* called when received response
response.type -> 'string', 'Buffer', 'JSON'
response.payload -> typeof string, Buffer or Object
*/
})
.catch(function (reason) {
// request failed
console.error(reason);
});
onRequest(callback)
defines a request handler callback function. The handler function is called internally on each request received from connected client.
callback function required; callback takes these arguments:
object req the request object with properties object connection, string topic, string type, string|object|Buffer payload and object meta
object res the response object with function send()
use res.send(message, meta) to respond to the request with string|object message and optional meta data object.
Examples:
respond with string "foo":
clientB.onRequest(function (req, res) {
/* called when received request
req.type -> the payload data type 'string', 'Buffer', 'JSON'
req.payload -> typeof string, Buffer or Object
req.connection -> connection object
req.topic -> string mqtt topic
req.meta -> null|object meta object data
*/
res.send('foo', {bar: 'baz'});
});
respond with object
clientB.onRequest(function (req, res) {
var o = {foo: 'bar'};
res.send(o);
});
respond with file content
clientB.onRequest(function (req, res) {
var bufferRespond = fs.readFileSync('filename');
res.send(bufferRespond);
});
sharedSecret(callback)
defines a connection-specific callback function to retrieve the shared secret required to connect. The callback function will be called internally on incoming as well as outgoing connection requests.
callback function required; first argument clientId is the connecting client id or the id of client to connect, the second cb a callback that takes the shared secret or falsy when connection should be refused.
function onSharedSecret (clientId, cb) {
if (clientId === 'client-b') {
// continue connecting with client b using shared secret
cb('shared-secret-a-b');
}
else {
// refuse connect
cb();
}
}
clientA.sharedSecret(onSharedSecret);
connect([toClientId[, sharedSecret]])
connect to broker or client with toClientId set.
toClientId string, optional. if set, connects to a client with the specified id. if omitted only connects to the broker.
sharedSecret string optional. if set it is used as the shared secret when connecting the client
Example:
clientB.sharedSecret(function (clientId, callback) {
if (clientId === 'client-a') {
callback('shared-secret-a-b')
}
else {
callback(null);
}
});
// connect client-b to broker
clientB.connect()
.then(..);
..
// connect client-a to client-b
clientA.connect('client-b', 'shared-secret-a-b')
.then(function () {
// called when client-b is connected
})
.catch(function (reason) {
// connect to client-b failed
console.error(reason);
});
ping(toClientId)
send ping request to client. if not yet connected, connects to client.
toClientId string, optional. if set, connects to a client with the specified id. if omitted only connects to the broker.
returns Promise resolved, when ping-ack was received, reject on timeout.
disconnect([fromClientId])
disconnect from broker or client with toClientId set.
fromClientId string, optional. if set, disconnects from a client with the specified id. if omitted, completely disconnects also also from the broker.
Example:
// completely disconnect client-b
clientB.disconnect()
.then(..);
..
// disconnect from client-b only
clientA.disconnect('client-b')
.then(..)
Events
broker.connect
fired when client connects to broker
client.connect
fired when a client connects
Arguments:
string clientId the client id of the connected client
Example:
client.on('client.connect', function (clientId) {
log('on.client.connect ' + clientId);
});
include client into web page
<script src="../build/mqtt-reqres-browser.js"></script>
// or minified
<script src="../build/mqtt-reqres-browser.min.js"></script>
..
<script type="text/javascript">
client = new MqttReqRes();
..
</script>
use the client as a module
requires node >= 5.10.0
var MqttReqRes = require('mqtt-reqres');
test
runs mocha specs in /test
$ npm test
// or
$ npm run test:debug
you may also open test/index.html in browser to play around with a client live frontend - this requires to have a websocket mqtt broker running (mqtt-reqres-broker):
$ npm run broker
// start broker with options
$ npm run broker -- -h 127.0.0.1 -p 9999
other tasks
// build all
$ npm run build
// create build/mqtt-reqres-browser.js
$ npm run browserify
// create annotated source documentation in doc/
$ npm run build:docs
// minify browser version (http://coderaiser.github.io/minify/)
$ npm run minify:browser
mqtt-reqres
mqtt request/response client based on mqttjs
API
Stability: Experimental
Methods
MqttReqRes([options])
constructor
options:
returns instance of MqttReqRes
Example:
request(toClientId[, payload, meta])
send a request to an other client.
toClientId string, required. the receiver's client id
payload string|object|Buffer, optional. the message string or object to be sent. for
Buffer
type see Node docsmeta object, optional. an object to be sent additionaly.
returns Promise which resolves to object
response
Example:
onRequest(callback)
defines a request handler callback function. The handler function is called internally on each request received from connected client.
callback function required; callback takes these arguments:
connection
, stringtopic
, stringtype
, string|object|Bufferpayload
and objectmeta
send()
use
res.send(message, meta)
to respond to the request with string|objectmessage
and optional meta data object.Examples:
respond with string "foo":
respond with object
respond with file content
sharedSecret(callback)
defines a connection-specific callback function to retrieve the shared secret required to connect. The callback function will be called internally on incoming as well as outgoing connection requests.
callback function required; first argument
clientId
is the connecting client id or the id of client to connect, the secondcb
a callback that takes the shared secret or falsy when connection should be refused.connect([toClientId[, sharedSecret]])
connect to broker or client with
toClientId
set.toClientId string, optional. if set, connects to a client with the specified id. if omitted only connects to the broker.
sharedSecret string optional. if set it is used as the shared secret when connecting the client
Example:
ping(toClientId)
send ping request to client. if not yet connected, connects to client.
toClientId string, optional. if set, connects to a client with the specified id. if omitted only connects to the broker.
returns Promise resolved, when
ping-ack
was received, reject on timeout.disconnect([fromClientId])
disconnect from broker or client with
toClientId
set.fromClientId string, optional. if set, disconnects from a client with the specified id. if omitted, completely disconnects also also from the broker.
Example:
Events
broker.connect
fired when client connects to broker
client.connect
fired when a client connects
Arguments:
Example:
include client into web page
use the client as a module
requires node >= 5.10.0
test
runs mocha specs in /test
you may also open
test/index.html
in browser to play around with a client live frontend - this requires to have a websocket mqtt broker running (mqtt-reqres-broker):other tasks
see all npm tasks defined in package.json.
build docs
create annotated source documentation in
doc/
folder, uses groc