SubEtha Peer Events

Communicate with SubEtha peers using arbitrary events

by Bemi Faison

Description

SubEtha Peer Events (or PE) is a SubEtha-Client plugin that enables publishing and subscribing events between peers. This plugin is bundled with the SubEtha module.

Note: Please see the SubEtha project page, for important background information, plus development, implementation, and security considerations.

Usage

PE provides methods to communicate events to channel peers, once the client connection is established. (Events are arbitrary strings that trigger callbacks.) Event subscription is done via the existing Client#on() method.

Communicating events

The #emit() and #send() methods share the same argument signature. Simply provide an arbitrary event name - i.e., a string with one or more characters. Any additional arguments are passed along to peers that have subscribed to your event. (The arguments must conform to the structured clone algorithm)

Use Client#emit() to broadcast your event to all peers in your channel. Below demonstrates rigging a client to broadcast once a connection is made.

var client = new Subetha.Client();
client.on('::connect', function () {
  this.emit('hello world!', 'some', 'additional', 'arguments');
});

Use Peer#send() to message a single peer. Below demonstrates rigging a client to respond to sending peer - the Peer instance via the event object. (Peers are available by id within the Client@peers hash.)

var client = new Subetha.Client();
client.on('hello world!', function (evt) {
  evt.peer.send('hello back!', 'from', 'me');
});

Note: You may not send events that begin with a double-colon (::). These are reserved for network events, published by the SubEtha-Client module.

Handling Events

The Client#on() method may be used to subscribe to peer events sent with #emit() or #send(). Simply subscribe to the same event passed to those methods and provide a callback function.

Callbacks of peer events receive a peer-event object. As well, if additional parameters were passed to #emit() or #send(), they will likewise be passed as additional, arbitrary arguments to the callback.

While the peer-event object contains lots of useful information, it's most important member is peer: the client whom sent the event. This is a Peer instance from the client's own @peers hash, meaning any state you set before (or now) is available now (or later).

Below demonstrates a callback which tracks the number of times each peer sends a given event.

var client = new Subetha.Client().open('flu@public');

client.on('ah... ah-choo!!', function (evt) {
  var peer = evt.peer;

  // initalize "cnt" member, if not present
  if (!peer.hasOwnProperty('cnt')) {
    peer.cnt = 0;
  }

  // increment count
  peer.cnt++;

  console.log('peer %s sneezes: %d', peer.id, peer.cnt);
});

API

Below is reference documentation for the SubEtha Peer Events module - i.e., additions to SubEtha-Client module.

Note: Instance methods are prefixed with a pound-symbol (#). Instance properties are prefixed with an at-symbol (@). Static members are prefixed with a double-colon (::).

Subetha::Client

Peer event object

Callbacks receive the following peer-event object, along with any additonal parameters, sent by the peer.

• data - An array of any additional arguments passed to the #emit() or #send() method.
• id - Unique identifier for this event.
• peer - The peer that sent this message.
• timeStamp: The time (in milliseconds) when the event occurred.
• type - The original string passed to #emit() or #send().

Client#emit()

Broadcast a message to channel peers.

client.emit(event [, args, ...]);

• event: (string) The event to trigger.
• args: (mix) Remaining arguments, to be sent as additional parameters.

The event argument may not begin with a double-colon (::).

Returns true when the event is sent. Otherwise, false.

Subetha::Peer

Peer#send()

Send an event to this peer.

peer.send(event [, args, ... ])

• event: (string) The event to trigger.
• args: (mix) Remaining arguments, to be sent as additional parameters.

The event argument may not begin with a double-colon (::).

Returns true when the event is sent. Otherwise, false.

Installation

SubEtha Peer Events works within, and is intended for, modern JavaScript browsers. It is available on bower, component and npm as a CommonJS or AMD module.

If SubEtha Peer Events isn't compatible with your favorite runtime, please file an issue or pull-request (preferred).

Dependencies

SubEtha Peer Events depends on the following module:

• SubEtha-Client

Web Browsers

Use a <SCRIPT> tag to load the subetha-client-pe.min.js file in your web page. The file does not include the SubEtha-Client module. You must include this as well, before loading this plugin, which updates members of the Subetha namespace, in the global scope.

  <script type="text/javascript" src="path/to/subetha-client.min.js"></script>
  <script type="text/javascript" src="path/to/subetha-client-pe.min.js"></script>
  <script type="text/javascript">
    // ... SubEtha dependent code ...
  </script>

Note: The minified file was compressed by Closure Compiler.

Generally speaking, the standalone version of this plugin should not be installed manually, since it's bundled with the SubEtha module. Install the SubEtha module instead - a rollup of the SubEtha-Client and recommended plugins.

Package Managers

• npm install subetha-client-pe
• component install bemson/subetha-client-pe
• bower install subetha-client-pe

Note: The npm package uses subetha-client as a peerDependency.

AMD

Assuming you have a require.js compatible loader, configure an alias for the SubEtha Peer Events module (the term "subetha-client-pe" is recommended, for consistency). The subetha-client-pe module exports a module namespace.

require.config({
  paths: {
    'subetha-client-pe': 'libs/subetha-client-pe'
  }
});

Then require and use the module in your application code:

require(['subetha-client-pe'], function (Subetha) {
  // ... SubEtha dependent code ...
});

Caution: You should not load the minified file via AMD. Instead use AMD optimizers like r.js, in order to roll-up your dependency tree.

License

SubEtha-Event is available under the terms of the Apache-License.

Copyright 2014, Bemi Faison