substream
Volatile namespaces for Primus
Want to see pretty graphs? Log in now!Want to see pretty graphs? Log in now!
npm install substream
SubStream
SubStream is a simple stream multiplexer for Primus. It allows you to create
simple message channels which only receive the information you send to it. These
channels are in fact, streams, which is why this module is called
SubStreams
because it adds small streams on top of the main stream and intercepts them.
Installation
npm install --save substream
The module can only be used in conjunction with Primus so make sure that your application is using that as real-time backend.
Getting started
In all the code examples we assume that the following code is present:
'use strict'; var Primus = require('primus') , http = require('http'); var server = http.createServer() , primus = new Primus(server); // // Custom code here, just above the listen call. // server.listen(8080);
Which is the most minimal bootstrapping code required to create a Primus
powered server. Once you've setup the server you need to add
SubStream as
a plugin in to Primus:
// // The `primus.use` method adds the plugin to primus. It requires a name in // order to easily retrieve it again, it needs to be unique but for the sake of // clairity, we're using to use substream as a name. // primus.use('substream', require('substream'));
After you've added plugins, you might want to re-compile the client library that
Primus serves as it automatically the client-side plugin to the framework as
well as the custom
substream.js library to create the actual name spaces. To
save the client just run:
primus.save(__dirname +'/primus.js');
But this is only needed if you serve the file manually and not through the
automatically generated
/primus/primus.js path. Now that we've set everything
up correctly we can start creating some substreams.
The client
To create or access a
substream in the Primus client start off with making
a connection:
var primus = new Primus('http://<your url here:whateverportnumber>'); var foo = primus.substream('foo');
The
substream method automatically creates a namespaced stream if you didn't
create it before. Or it will return your previously created stream when you call
it again. So now we have a
foo stream we can just write to it:
foo.write('data');
Awesome, all works as intended. But this was just one single substream, we can add more:
var bar = primus.substream('bar') , baz = primus.substream('baz');
You can create an infinite amount substreams on top of one single base stream. The data is not leaked between streams. It's all "sandboxed".
As the returned substreams are
streams or
eventemitters we can just listen
to
data,
end or
close events. But it also proxies all the other events
that Primus emits such as the
reconnect,
offline events etc. (The full
list is in the Primus README.md). So for receiving and writing data you can just
do:
bar.on('data', function () { }); bar.write('hello from bar'); foo.on('data', function (data) { console.log('recieved data', data); }).on('end', function () { console.log('connection has closed or substream was closed'); });
The server
The server portion of this module isn't that different than the client portion. It follows the same API stream/eventemitter API:
primus.on('connection', function (spark) { var foo = spark.substream('foo') , bar = spark.substream('bar') , baz = spark.substream('baz'); foo.on('data', function (data) { console.log('foo received:', data); }); // // You can even pipe data // fs.createReadSteam(__dirname +/'example.js').pipe(bar, { end: false }); // // To stop receiving data, simply end the substream: // baz.end(); })
License
MIT