happner-client

The client for happner-2 and happner cluster services.

npm install happner-client

Usage

Create client instance.

1var HappnerClient = require('happner-client');
2var client = new HappnerClient({
3  requestTimeout: 10 * 1000, // (default) milliseconds timeout on api request (set ack)
4  responseTimeout: 20 * 1000, // (default) timeout awaiting response
5  logger: null // (defualt) optional happner-logger
6});

Connect

1var optionalInfo = {
2  // meta data for login
3  ///////////////////// in $origin
4}
5client.connect(
6  { // connection
7    host: 'localhost',
8    port: 55000
9  },
10  { // options
11    protocol: 'https',
12  	username: '_ADMIN',
13    password: 'happn',
14    allowSelfSignedCerts: true,
15    info: {}
16  }
17).then(...).catch(...); // also supports callback
18
19
20// connection can be defaulted (eg. in browser)
21client.connect(null, {username: '_ADMIN', password: 'happn'}, function (e) {
22})

Create and connect

the simpler way: (v12.6 onwards)

1const client = await HappnerClient.create({
2  host: 'localhost',
3  port: 55000,
4  username: '_ADMIN',
5  password: 'xxx'
6});

Login with token and logout

it is possible to connect with another clients token, the call to .logout() will invalidate your connection token, and disconnect all clients that have used it to login with:

1const connectionOptions = {
2  host: 'localhost',
3  port: 55000,
4  username: '_ADMIN',
5};
6const client = await HappnerClient.create({ ...connectionOptions, password: 'xxx' });
7let token = client.dataClient().session.token;
8let otherClient = await HappnerClient.create({ ...connectionOptions, token });
9test.expect(otherClient.dataClient().status).to.be(1); // status 1 is connected
10await client.logout();
11await test.delay(2e3); // wait a second
12test.expect(otherClient.dataClient().status).to.be(2); // status 2 is disconnected

Events

1client.on('connected', function () {
2  // event fired on successful connection to server
3});
4
5client.on('reconnected', function () {
6  // event fired on successful reconnection to server
7});
8
9client.on('disconnected', function () {
10  // event fired when disconnected from server
11});
12
13client.on('reconnecting', function () {
14  // event fired when attempting to reconnect
15});
16
17client.on('error', function (e) {
18  // includes model verification mismatches
19});

Construct your API

1var kitchenModel = {
2  fridge: {
3    version: '^1.0.0', // requires that server has matching version of fridge component
4    methods: {
5      getTemperature: {
6        // optional parameters for clientside validation
7        params: [
8          {name: 'shelves', type: 'array'}
9        ]
10      }
11    }
12  }
13};
14
15var kitchen = client.construct(kitchenModel);

Use API functions

1// with callback
2kitchen.exchange.fridge.getTemperature(['top', 'middle'], function (e, temps) {});
3
4// with promise
5kitchen.exchange.fridge.getTemperature(['top', 'middle'])
6	.then(function (temps) {})
7	.catch(function (e) {})

Listen to API events

1kitchen.event.fridge.on('/eventName', function (data) {});

Discover component methods

NB: this will only work if you connect before you construct

1//initialize the client with discover Methods true
2const client = new HappnerClient({ discoverMethods: true });
3
4//set up your model, declaring which components you wish to discover
5var model = {
6  component1: {
7    version: '^1.0.0'
8    //no need for method declarations
9  },
10  component2: {
11    version: '^1.0.0'
12    //no need for method declarations
13  }
14};
15//on connection the remote mesh schema will be pulled
16await client.connect(null, {
17  username: '_ADMIN',
18  password: 'xxx'
19});
20//on construct the components in the model will be updated with the available methods
21const createdApi = createdClient.construct(model);
22await createdApi.component1.discoveredMethod();

Access happn data points directly, via the dataClient

1//assuming we have connected
2//var client = new HappnerClient(...
3//client.connect(...
4var dataClient = client.dataClient();
5
6//dataClient is the underlying happn-3 client for the happner-client connection, so you have all the happn-3 goodness:
7dataClient.on('/test/point', function(data){
8
9}).then(...);
10
11dataClient.set('/test/point', {my: 'data'}).then(...)
12
13dataClient.get('/test/point').then(...)
14
15dataClient.remove('/test/point').then(...)
16

see this test for a full demonstration

Browser usage

Assuming served from happner-2 packaged /api/client script

1<!DOCTYPE html>
2<html lang="en">
3<head>
4  <meta charset="UTF-8">
5  <title>Title</title>
6
7  <!-- includes Happner.HappnerClient -->
8  <script src="/api/client"></script>
9
10  </head>
11<body>
12
13  <script>
14
15    var client = new Happner.HappnerClient({
16      requestTimeout: 10 * 1000,
17      responseTimeout: 20 * 1000
18    });
19
20    var model = {
21      'component': {
22        version: '^2.0.0',
23        methods: {
24          method1: {}
25        }
26      }
27    };
28
29    var api = client.construct(model);
30
31    client.connect()
32
33      .then(function () {
34        // subscribe to events (requires connected)
35        api.event.component.on('test/event', function (data, meta) {
36          console.log('EVENT', meta.path);
37        });
38      })
39
40      .catch(function (error) {
41        console.error('connection error', error);
42      });
43
44    // repeat call on exchange
45    setInterval(function () {
46
47      api.exchange.component.method1()
48        .then(function (reply) {
49          console.log('REPLY', reply);
50        })
51        .catch(function (error) {
52          console.error('ERROR', error);
53        });
54
55    }, 1000);
56
57  </script>
58
59</body>
60</html>

happn-client lite

this version of the client does not require the construction of the expected API, the calls are transactional with a the same payload structure

connect, login with a token, call a method, listen to an event and finally logout

1const LightClient = require('happner-client').Light;
2const Happner = require('happner-2');
3const DOMAIN = 'DOMAIN_NAME';
4
5const serverInstance = await Happner.create({
6  domain: DOMAIN,
7  happn: {
8    secure: true,
9    adminPassword: 'xxx',
10  },
11  modules: {
12    remoteComponent: {
13      instance: {
14        remoteMethod: async (arg1, arg2, $happn) => {
15          $happn.emit(`remoteEvents/1`, { arg1, arg2 });
16          return `${arg1}/${arg2}`;
17        },
18      },
19    },
20  },
21  components: {
22    remoteComponent: {},
23  },
24});
25
26const connectionOptions = {
27  host: 'localhost',
28  port: 55000,
29  username: '_ADMIN',
30  domain: DOMAIN, // the domain of the cluster or the name of the happner mesh you are connecting to
31};
32
33const myClient = await LightClient.create({ ...connectionOptions, password: 'xxx' });
34
35// call a remote method like so, will throw a not implemented error if the remote component or method does not exist:
36const result = await myClient.exchange.$call({
37  component: 'remoteComponent',
38  method: 'remoteMethod',
39  arguments: ['arg1', 'arg2'],
40});
41
42// eslint-disable-next-line no-console
43console.log(result);
44
45// listen for an event every time it happens
46const onEventId = await myClient.event.$on(
47  { component: 'remoteComponent', path: 'remoteEvents/*' },
48  function (eventData) {
49    // our handler does something with the event data
50    // eslint-disable-next-line no-console
51    console.log('$on:' + JSON.stringify(eventData));
52  }
53);
54
55// unlisten by event handle
56await myClient.event.$off(onEventId);
57
58// or unlisten by component and path
59await myClient.event.$offPath({ component: 'remoteComponent', path: 'remoteEvents/*' });
60
61// listen for an event once only, does equivalent of $off after the event is handled
62await myClient.event.$once(
63  { component: 'remoteComponent', path: 'remoteEvents/*' },
64  function (eventData) {
65    // our handler does something with the event data
66    // eslint-disable-next-line no-console
67    console.log('$once:' + JSON.stringify(eventData));
68  }
69);
70
71// call again for our once to kick in
72await myClient.exchange.$call({
73  component: 'remoteComponent',
74  method: 'remoteMethod',
75  arguments: ['arg1', 'arg2'],
76});
77
78// call yet again - ensure once only fired once
79await myClient.exchange.$call({
80  component: 'remoteComponent',
81  method: 'remoteMethod',
82  arguments: ['arg1', 'arg2'],
83});
84
85// grab our session token
86let token = myClient.dataClient().session.token;
87// create a new session off the token
88let myOtherClient = await LightClient.create({ ...connectionOptions, token });
89// eslint-disable-next-line no-console
90console.log(`status === 1: ${myOtherClient.dataClient().status === 1}`);
91
92// parent client logout
93await myClient.logout();
94// possible need for delay...then:
95// eslint-disable-next-line no-console
96console.log(`status === 2: ${myOtherClient.dataClient().status === 2}`); // child myOtherClient disconnected, as it was authenticated via parent myClient's token
97serverInstance.stop();