@pubkeeper/client

Pubkeeper Client

@pubkeeper/client enables web browsers to join, consume, and produce content on a Pubkeeper network.

Concepts & Terms

• Brew : A protocol/method of delivery, e.g. WebSocket, SocketIO, WebRTC, HTTP
• Brewer : An object bound to a specific topic that accepts a data transports it to matched patrons.
• Patron : A consumer bound to one or more topics, it receives data from matched brewers.

Installation

In a browser:

<script src="pubkeeper-client.js"></script>

Using npm:

$ npm install --save @pubkeeper/client

Then, load using ES5 require() syntax…

var PubkeeperClient = require('@pubkeeper/client').PubkeeperClient;

…or with ES2015+ import syntax:

import { PubkeeperClient } from '@pubkeeper/client';

Basic Syntax

Client Configuration

import { PubkeeperClient } from '@pubkeeper/client';
import { WebSocketBrew } from '@pubkeeper/brew-websocket';
import { PubkeeperAesCbcCrypto } from '@pubkeeper/crypto-cjs-aes-cbc';

// Create a client
const client = new PubkeeperClient({
  server: 'wss://192.168.100.191:9898/ws',
  jwt: "[your JWT]",
  crypto: new Map([
    PubkeeperAesCbcCrypto,
  ]),
  brews: [
    new WebSocketBrew({
      brewerConfig: {
        hostname: '192.168.100.191',
        port: 8000,
        secure: true,
      },
    }),
  ],
});

client.connect();

Note: This client is the core pubkeeper client, as such it does not include any crypto or brews. If you want a pre-packaged version suitable for general usage see @pubkeeper/browser-client

Brewing Setup

To produce data into the Pubkeeper network you will need to create a brewer. The example below will setup a Brewer with the topic of topic.information

client.addBrewer('topic.information', (brewer) => {
  // brewer has been *matched* by pubkeeper, i.e. there is
  // at least one patron of this topic.
  let counter = 0;

  const id = setInterval(() => {
    brewer.brewJSON({ counter });
    counter += 1;
  }, 1000);

  return function teardown() {
    // teardown function will be called when there are
    // _no_ more patrons or this brewer has been removed.
    clearInterval(id);
  };
});

Patron Setup

To listen to someone who is brewing information, you need to subscribe to the topic, and configure a callback to occur when there is data available for processing.

client.addPatron('weather.*', (patron) => {
  // patron has been *matched* by pubkeeper, i.e. there is
  // at least one brewer of this topic.
  function handler(bytes, meta) {
    console.log(meta.from, meta.topic, patron.id, bytes);
  };

  patron.on('message', handler);

  return function teardown() {
    // teardown function will be called when there are
    // _no_ more brewers or this patron has been removed.
    patron.off('message', handler);
  };
});

Brewer/Patron Connections

The Patron message event is always fired with a Uint8Array as data, no matter which brew*() method was called on the brewing side. You need to handle parsing/casting those bytes.

For instance, given a brewer:

client.addBrewer('tick', (b) => {
  let id, count = 0;
  (function tick() {
    id = setTimeout(tick, 1000);
    b.brewJSON({ count });
  })();
  return () => { clearTimeout(id); };
});

Then on the patron side, it would look like this;

client.addPatron('tick', (p) => {
  const handler = (bytes) => {
    const text = new TextDecoder().decode(bytes);
    const value = JSON.parse(text);
    console.log(value.count);
  };
  p.on('message', handler);
  return () => { p.off('message', handler); };
});

NOTE This will be resolved in future versions of the protocol.

State Change Events

Brewers and Patrons will be notified when thier couterparts are added or removed:

client.addBrewer('topic.information', (brewer) => {
  const handleAdded = ({ id, topic }) => {
    console.log('patron (%s) added', id);
  };

  const handleRemoved = ({ id }) => {
    console.log('patron (%s) removed', id);
  };

  // setup
  brewer.on('added', handleAdded);
  brewer.on('removed', handleRemoved);

  return function teardown() {
    // cleanup
    brewer.off('added', handleAdded);
    brewer.off('removed', handleRemoved);
  };
});

PubkeeperClient Class

The PubkeeperClient manages the connection to a pubkeeper server.

new PubkeeperClient(options)

Name	Type	Description
options	ClientOptions	The options for this pubkeeper client

ClientOptions : object

These options can be given to a PubkeeperClient to customize its behavior.

Name	Type	Default	Description
server	string	-	Websocket URL of the pubkeeper server
jwt	string	-	Auth token for the pubkeeper server
brews	Array<Brew>	[]	Supported brews of this client
crypto	Map<*,Crypto>	new Map	Supported crypto mappings for this client
protocols	Map<*,Protocol>	new Map	Supported protocol mappings for this client. Defaults to the legacy protocol
maxRetries	number	Infinity	Maximum number of connection retries
maxTimeout	number	10000	Maximum timeout between retries (in milliseconds)

Examples

Using ES2015 Promise:

const client = new PubkeeperClient(config)

client.connect().then(() => {
  console.log('ready');
});

Using ES2017 async/await:

(async () => {
  const client = new PubkeeperClient(config)
  await client.connect();
  console.log('ready');
})();

Members

.status : string

Returns the status of this client. Can be one of the following:

Value	Description
'connecting'	Attempting to connect.
'connected'	Connected
'reconnecting'	Has lost the connection, and has queued a reconnection attempt.
'disconnected'	Disconnected
'dead'	Given up retrying to connect

Methods

.connect({ wait = true } = {}) : Promise?

Connect to the configured pubkeeper server. If { wait: true } is specified, this function will return a Promise that will be resolved when the connection to the pubkeeper server has been finalized. Passing { wait: false } will immediately return undefined and the server may or may not be connected yet.

.disconnect()

Disconnect from the server.

.addBrewer(topic[,[ options,] matched]) : Brewer

Create a new brewer of topic.

Name	Type	Description
topic	string	The topic
options	BrewerOptions
matched	Function	Callback that is invoked when the brewer has been matched with a patron

BrewerOptions : object

These options can be given to the PubkeeperClient#addBrewer method to customize the brewers behavior.

Name	Type	Default	Description
autoRemoveListeners	boolean	false	Automatically remove all event listeners on unmatch
brews	Array<(string|Brew)>	-	A subset of brews to use for this brewer, defaults to all registered brews.
id	string	-	The UUID of this brewer, defaults to a random UUIDv4
waitForBrews	(number|boolean)	250	The maximum wait time to wait when brewing data for brew connections to stablize.

Examples

Using the matched callback:

client.addBrewer('topic', (brewer) => {
  brewer.brewText('somebody is out there!');
});

With extended options:

// Do not wait for brew connections to stablize before sending.
client.addBrewer(
  'topic',
  { waitForBrews: false },
  (brewer) => {
    brewer.brewText('somebody is out there!');
  },
);

Managing resources with teardown function:

client.addBrewer(
  'device.motion',
  (brewer) => {
    const handler = ({ acceleration }) => {
      brewer.brewJSON(acceleration);
    };
    window.addEventListener('devicemotion', handler);
    return () => {
      window.removeEventListener('devicemotion', handler);
    };
  },
);

.removeBrewer(brewer)

Remove a brewer from this client.

Examples

const ref = client.addBrewer('topic', matchedFn);
/* ...later */
client.removeBrewer(ref);

.addPatron(topic[,[ options,] matched]) : Patron

Create a new patron of topic.

Name	Type	Description
topic	string	The topic
options	PatronOptions
matched	Function	Callback that is invoked when the patron has been matched with a brewer

PatronOptions : object

These options can be given to the PubkeeperClient#addPatron method to customize the patrons behavior.

Name	Type	Default	Description
autoRemoveListeners	boolean	false	Automatically remove all event listeners on unmatch
brews	Array<(string|Brew)>	-	A subset of brews to use for this patron, defaults to all registered brews.
id	string	-	The UUID of this patron, defaults to a random UUIDv4

Examples

Using the matched callback:

client.addBrewer('topic', (patron) => {
  const handler = (data, meta) => { /* process data */ };
  patron.on('message', hanlder);
  return () => { patron.off('message', handler); };
});

.removePatron(brewer)

Remove a patron from this client.

Examples

const ref = client.addPatron('topic', matchedFn);
/* ...later */
client.removePatron(ref);

Brewer Class

A brewer is a publisher of information in a pubkeeper system.

Members

.id : string

the uuid of this brewer

.brews : Array<string>?

the subset of brew names that this brewer is using.

.topic : string

the topic this brewer is bound to

.count : number

current count of matched patrons

.isMatched : boolean

Is the brewer currently matched with any patrons

Methods

.brew(bytes[, options]) : Promise

Publish binary data to a brewer.

Name	Type	Description
bytes	(Uint8Array|Uint8ClampedArray)	Binary data to brew
options	object
options.waitForBrews	number?	Override the brewers config

.brewText(text[, options]) : Promise

Publish text as a UTF-8 encoded byte array.

Name	Type	Description
text	string	text to brew
options	object
options.waitForBrews	number?	Override the brewers config

.brewJSON(value[, options]) : Promise

Publish value using JSON.stringify.

Name	Type	Description
value	*	value to serialize and brew
options	object
options.waitForBrews	number?	Override the brewers config

.on(event, fn[, context]) : this

.addListener(event, fn[, context]) : this

Add a listener for a given event.

.off(event, fn[, context[, once]]) : this

.removeListener(event, fn[, context[, once]]) : this

Remove the listeners of a given event.

Events

added

Fired when a matched patron is added.

Name	Type	Description
e	object
e.id	string	UUID of the added patron
e.topic	string	topic of the brewer

removed

Fired when a matched patron is removed.

Name	Type	Description
e	object
e.id	string	UUID of the removed patron

Patron Class

A patron is a subscriber of information in a pubkeeper system.

Members

.id : string

the uuid of this patron

.brews : Array<string>?

the subset of brew names that this patron is using.

.topic : string

the topic this patron is bound to

.count : number

current count of matched brewers

.isMatched : boolean

Is the patron currently matched with any brewers

Methods

.on(event, fn[, context]) : this

.addListener(event, fn[, context]) : this

Add a listener for a given event.

.off(event, fn[, context[, once]]) : this

.removeListener(event, fn[, context[, once]]) : this

Remove the listeners of a given event.

Events

added

Fired when a matched brewer is added.

Name	Type	Description
e	object
e.id	string	UUID of the added brewer
e.topic	string	topic of the brewer

removed

Fired when a matched brewer is removed.

Name	Type	Description
e	object
e.id	string	UUID of the removed brewer

message

Fired when a message is recieved from a brewer.

Name	Type	Description
data	Uint8Array	The binary data from the brewer
meta	object
meta.topic	string	topic of the brewer that brewed this data
meta.from	string	UUID of the brewer that brewed this data