corridors

Corridors.js

A lightweight socket.io based library to provide a clean, abstract way to manage web socket rooms and users.

Installation

npm install corridors --save

Usage

corridors uses a three step process to get up and running: init, configure, and run. The init phase requires a server (of your creation) to start socket.io. The configure stage has a series of options that you can pick from, including whether or not to allow room keys, user authentication (set the "shouldAllowUser: function(user, data)" hook - default returns true always), maximum members per room. There are defaults set for everything as well (see Documentation) The run stage applies all the settings.

corridors also has a reset function that destroys all settings and removes listeners, essentially restoring the state of the system to the init stage.

Example:

var app = require('express')();
var express = require('express');
var server = require('http').Server(app);
var corridors = require('corridors');

app.use(express.static('public'));
server.listen(4004);

corridors.init(server);

corridors.configure({
  maxMembers: 3,
  allowKeys: true,
  messages: {
    "say":function (user, data) {
      user.room._tellRoom("new message", {message: data.message, name: user.name});
    }
  },
  configureRoom: {
    // Properties and methods of each room can be put here.
  },
  configureUser: {
    name: ""
  },
  onRegistrationSuccess: function (user, data) {
    user.name = data.name
  }
});
corridors.run();

The client side of corridor (included in install, very small file) is essentially a method that applies special listeners to sockets. Here's an example of multiple clients connecting, and one client sending a message while the other receives it.

var socket = io.connect("http://localhost:4004");
corridorify(socket, {
  registrationData: {
    name: "testuser!"
  },
  onConnect: function () {
    console.log("I am connected and ready");
  },
  onReject: function () {
    console.log("I was rejected!");
  }
});

Settings

The options for configuration of the server can be found in the defaults of the index.js file of corridors - each option has a default:

var defaults = {
  maxMembers: 1,
  allowKeys: true,
  userToRoomImmediately: false,
  shouldAllowUser: function (socket, data) {
    return true;
  },
  onRegistrationSuccess: function (user, registrationData) {},
  messages: {},
  configureRoom: {
    begin: function () {},
    removeMember: function (user) {}
  },
  configureUser: {}
};

Each of the functions or settings above does something, including the functions. The settings for the client side corridors are as follows:

var defaults = {
  registrationData: {
    roomKey: null
  },
  onConnect: function () {},
  onReject: function () {}
};

where onConnect happens when the socket makes connection with the server (but is not registered, thus not put into a room or lobby yet), and onReject occurs when the user is asking for a room that is already full, or doesn't meet the authentication requirements specified in the server side "shouldAllowUser" function, etc. The registration data parameter can hold any information (must have the roomKey), and you can access that data by the onRegistrationSuccess server side function.

Notes

Room keys are more like requests than keys. Let's say Bob and Joe want to go to a private room to chat. They can make up their own room name, like "fort" and use that as their room key. Thus, only people who use the room key "fort" can get into their room. Also, allowing keys still allows "null" as a key. Entering "null" as a key is synonymous with no preference, so the room id will be generated by uuid. If room names conflict, the users who requested the room last will have to pick a different key. Keys must be unique.

For more help, feel free to contact me with suggestions or questions.

Tests

npm test

Contributing

Please make sure that for any new or changed functionality, unit tests are also provided. I would also like to be notified if possible.

Release History

• 0.1.0 Initial release
• 0.1.1 Updated readme
• 0.1.2 Added room key functionality, authentication hook.
• 0.1.3 Added server-side registration hook (onRegistrationSuccess), fixed browser-reload bug
• 0.1.4 Added server-side userToRoomImmediately setting and associated tests.