toejough / wisper

minimalist websocket pub/sub with regex subscriptions

!!! ARCHIVED !!!

This project hasn't been maintained for a long time. I've officially shut it down. It was a fun experiment, but I'm not working in this language or space now or in the forseeable future, and it never got beyond alpha anyway.

I'm leaving it up in case anything here might be useful to someone. ¯\_(ツ)_/¯

wisper

regex pub/sub

---

WARNING: This project is in alpha. To be clear, that means I haven't asked anyone else to use it yet - the only testing it has is internal.

ANOTHER WARNING: It should be clear from the version, but this project is not stable. At the moment, I make no guarantees about API or features. I know what I intend, but a lot can happen in early development.

---

#Use

Here is a series of functions showing use, distilled from the tests. The tests (in the spec directory) showcase more advanced use.

var wisper = require('../wisper');
var hub = wisper.createHub();
var client = wisper.createClient();
var pattern = '^p.*$';

function listenOnHub(cb) {
    // set up hub
    hub.listen({port:8080}, cb);
}

function connectClient(cb) {
    // connect client to hub
    client.connect('http://127.0.0.1:8080', cb);
}

function subscribeClient(cb) {
    // subscribe client to p.*
    client.subscribe(pattern, cb);
}

function publishPublic(cb) {
    var messageToPublish = "is anyone out there?";
    var channelToPublishOn = "public";
    client.once('message', function checkMessage(message, channel, match) {
        // message is a json message
        // channel is the channel published on
        // match is the first pattern the hub thinks the client is subscribed to which matched the channel
        cb();
    });
    client.publish(messageToPublish, channelToPublishOn);
}

function unsubscribe(cb) {
    client.unsubscribe('^p.*$', cb);
}

function closeHub(cb) {
    hub.on('close', cb);
    hub.close();
}

function failToPublish(cb) {
    var messageToPublish = "is anyone out there?";
    var channelToPublishOn = "public";
    // expect client not to get message on channel and match
    client.once('message', function checkMessage(message, channel, match) {
        throw new VError("should never get here");
    });
    // expect the following to throw an exception for publishing on a closed client
    // the client will have become closed when the hub was closed.
    client1.publish(messageToPublish, channelToPublishOn, cb);
}

API

For now, see the source for the API. It's pretty well documented there.

wisper's Issues

Separate out the ws part into its own project

the pub/sub is the real thing here...WS is a fantastic medium, but the network transport should be abstracted from the functionality.

Update the server API to be more node-like

Add logging

Separate out the app-ack and messaging part of the project

This project should really be about the pub/sub, not about glue layers. App-ack is really useful, but it should be its own project or subproject that wisper just uses.

webproxy publish callback is not optional

if the user doesn't supply a callback and there is an error, the callback call fails and throws.

Replace bunyan with a lighter-weight logger

bunyan is more than this project needs. A primary goal was to be simple, and bunyan has way too many options, a binary, and recently (in another project) was found to be leaking memory. So...replace it with some thing lighter-weight.

cannot subscribe to a second channel on its own via webproxy

subscribe(foo) is fine
subscribe([foo, bar]) is fine
subscribe(foo); subscribe(bar) gets you an 'Error: not opened' every time.

Add nice MD documentation

Due to the immediate execution of emitted events, ws blows up during test teardown

I'd submit this as a bug to ws, but philosophically, I think the larger issue is that node's event emitter executes listeners immediately. The expectation I have had, and it seems the expectation ws acts on, is that I can predict what will happen in a single synchronous flow, and that emitting an event does not break interrupt execution. The second part of that is not true. Event emitters immediately execute registered listeners. Registered listeners can do anything.

To work around this, all event callback bodies and event emissions should be wrapped in 'process.nextTick' calls.

Allow multiple clients when used as a local service.

wisper has only one client when the service is used directly - this is a problem if different parts of your program want to subscribe to different channels.

clients aren't destroyed when their connection is lost

If the server gets an error when writing to a client, an error should be logged and that client should be destroyed (from the server side).

Perform argument checking up front

Argument-checking is important, and should be done up-front as much as possible.

Define and meet a coding/style standard for the project.

Testing takes 30s to actually end

There's a connection or socket or callback waiting, even after all the cleanup, so there's some missing cleanup when tearing down clients and servers.

Raze it

Total rewrite. The thing I care about here is regex pub/sub.

Rewrite everything to make heavy use of dependency injection. Define API's, make some example modules, and call it a day.

Core functionality - regex pub/sub.

Dependencies:

• logging
• app ack
• transport
• auth
• encryption

Negative testing

project needs negative testing.

Subscription to a webproxy should not fire a connect event on that proxy

The 'connect' event on the WebProxy object should be reserved for the proxy's initial connection as a publisher. When a new client profile is established, a 'client-connect' might be appropriate, but 'connect' is not.

Testing prints out 'null'

Somewhere there's an unintended print statement. Find it and squish it.