Mirage

Some might say that Mirage was created with a silver sparkplug in his mouth. On Cybertron, he was one of the planet's elite upper class, preferring to spend his days hunting turbo-foxes instead of involving himself in conflict. He is armed with a rifle which fires explosive, armor-piercing darts, but the most important piece of his arsenal in his function as a spy is his shoulder-mounted electro-disruptor, which can bend photons to make Mirage invisible, or appear to be where he is not, or even alter his physical appearance, hence his name.

His invisibility is invaluable for Primus. He now spends his time validating and generating session ids without the user even know it's there. It's a fully transparent process, it's invisible, it's Mirage. The generated session ids can be persisted if needed.

Installation

This is a plugin for the Primus framework and can be installed using npm:

npm install --save mirage

The --save tells npm to automatically add the installed version to your package.json.

This module assumes that you're using either the primus-emit or the primus-emitter module, for emitting events. Please see their sites to get detailed installation instructions.

Table of Contents

• Usage server
  • primus.id.timeout
  • primus.id.generator
  • primus.id.validator
• Usage client

Usage server

The mirage plugin should be the first plugin you load in Primus. This is because it will buffer incoming messages while it's validating or generating an id. If you don't do this, you will experience loss of data/messages!. Even the fortess-maximus plugin, that is generally added as the first plugin, should be loaded after mirage.

To add this plugin to your Primus server simply call the .plugin method on the Primus instance:

primus.plugin('mirage', require('mirage'));

Now that you've added the plugin, a new object, .id is available on your Primus instance. This object allows you to interact with the mirage plugin.

primus.id.timeout

The maximum time it should take to validate or generate a session id. If a timeout occurs all messages will be flushed and the callback will be called with an error. You can assign the timeout directly using:

primus.id.timeout = 2000;

It's also possible to configure this value using the mirage timeout option in the Primus constructor:

var primus = new Primus(httpsserver, {
  'transformer': 'engine.io',
  'mirage timeout': 5000
});

primus.id.generator

The generator method allows you to assign a custom id generator. By default we generate 8 random bytes using the crypto module. To set your own generator simply call the primus.id.generator with the function that you want to use.

The supplied function will receive 2 arguments:

1. spark A reference to the spark instance that is attempting to connect to your server.
2. function An error first callback which assumes to receive an error as first argument if generation failed and the generated id as second argument.

primus.id.generator(function generate(spark, fn) {
  asyncLookup(spark.query.customquerystring, function (err, account) {
    if (err) return fn(err);
 
    fn(undefined, account._id);
  });
});

primus.id.validator

The validator method is called when we receive a pre-defined id. By default we just allow all the things, but this can be overridden by supplying the primus.id.validator with a custom validator function.

The supplied function will receive 2 arguments:

1. spark A reference to the spark instance that is attempting to connect to your server.
2. function An error first callback. If you fail to validate the id, we assume that you pass this function an Error instance as first argument.

primus.id.validator(function validator(spark, fn) {
  accountdb.exists(spark.mirage, function (err, exists) {
    if (!err && !exists) err = new Error('Invalid id');
 
    fn(err);
  });
});

As you can see in the example above, the mirage id is introduced on the spark as spark.mirage. You can use this id to validate the connection. Now there are cases where you don't want to end the connection by supplying the callback with an error but you actually want to re-set a new session id. Well that's also possible with the validator as it can also act as a generator. To generate a new session id you can call the callback with the new id as the second argument:

primus.id.validator(function validate(spark, fn) {
  if (spark.mirage === 'old') return fn(undefined, 'new');
  if (spark.mirage === 'new') return fn(undefined, 'old');
 
  fn(new Error('The id is neither new or old'));
});

Usage client

The plugin also ships with a client API. This client API can be used for persisting the sessions across reconnects, refreshes and more. To re-use an id simply add the mirage option in the client when connecting.

var socket = new Primus('https://example.org', {
  mirage: readcookie('sessionid')
});

When you receive a new session id from the server we emit a mirage event:

socket.on('mirage', function (id) {
  savecookie('sessionid', id);
});

The id is also always available at: socket.mirage, but this is only after the connection has generated an id or if you've manually supplied it.

License

MIT