chirkut.js

1. Install node.js (>=0.4.0) from http://nodejs.org/

2. Install NPM from http://npmjs.org/

3. Follow ONLY any 1 step out of steps 4 and 5

4. If you have a source tarball, install chirjut.js by typing: npm install chirkut.js-VERSION.tar.gz -g

5. Check out the code using GIT from: git@github.com:directi/chirkut_deployment.git and follow either step 6a or 6b (depending up on your requirements)

6a. If you checked out from GIT and are NOT interested in hacking on chirkut.js, type (from within the source directory): npm install .

6b. To be able to continually update the source files within the source directory and have them as the ones used when chirkut.js is invoked, type: npm link (after entering the source directory - the one that contains package.json).

7. Setup the config file at /etc/bosh.js.conf (or any other location)

8. Run it using ./runner.sh

9. If you are using run-server.js itself (no auto-restart on crash), you need to enter chirkut.js --config=PATH_TO_CONFIG_FILE (if the config file is not /etc/bosh.js.conf)

10. The config file is a standard .js (javascript) file which is require()d by chirkut.js

11. To use the LATEST node-xmpp-bosh module, follow steps 13-16

12. Please read all about NPM at http://npmjs.org/ to get a better idea of how the package manager works.

13. $ cd /opt/

14. $ svn checkout http://node-xmpp-bosh.googlecode.com/svn/trunk/ node-xmpp-bosh-read-only

15. $ cd node-xmpp-bosh-read-only

16. $ npm link

Chirkut.js supports dynamically loadable plugins. You can load/unload plugins using the webrepl (default port is 9090 on the same host as the BOSH proxy).

Loading a plugin is really simple. Here is an example of loading the 'redis' plugin.

// Load the redis plugin
load_plugin('./plugins/redis.js', {
    server: server
});

The 'load_plugin' function above can be used to either load OR re-load a plugin. If the plugin is already loaded, it will call 'destroy' on the existing plugin (explained below) and re-load the plugin. You may change the source file between multiple invocations to 'load_plugin' and the latest version will be used.

A plugin is loaded by specifying the path of the plugin ('./pligins/redis.js') along with the single constructor argument that you want to pass to it. Note: Only 1 argument will be passed to the plugin.

The plugin may define 2 special methods 'init' and 'destroy' which will be invoked when the plugin is initialized and destroyed (only during plugin reload - NOT when the application terminates). Hence, in a healthy system, the 'init' function will be called exactly one time more (or the same number of times) than the 'destroy' function is called.

You may also unload a plugin dynamically in the running system (assuming that the plugin author has programmed for this behaviour). To unload the 'redis' plugin, you would type this:

// Unload the redis plugin
unload_plugin('./plugins/redis.js');

Note: Any exceptions that the plugin throws may crash the application, so ensure that you thoroughly test your plugin before deploying/reloading it into a LIVE system.

You can also load the plugins declaratively using the config file. See the example config file which loads up the email, redis and utils plugins.

There are 4 plugins available by default on Chirkut.js:

1. email.js: Used to send an email to users that have missed messages and
2. redis.js: Used to PUBLISH message packets to a redis server
3. utils.js: Allows you to send XMPP stanzas to open streams via the webrepl
4. stats.js: Used to query the server for statistics (explained in detail below)

Using:

To send a message to all connected users, type (in the webrepl):

utils.send_message_to_all('Message String')

To send the message from user 'notifications@talk.to', type:

utils.send_message_to_all('Message String', 'notifications@talk.to')

Using:

Check byte & packet stats using:

stats.all

{
   bytes_received:41075,
   bytes_sent:32397,
   bytes_transferred:73472,
   packets_received:137,
   packets_sent:227,
   packets_transferred:364
}

Check Stream Aggregated Stats using:

stats.streams.all

{
    running:3,
    total:3,
    total_time:0,
    average_time:0
}

Check Session Aggregated Stats using:

stats.sessions.all

{
    running:3,
    total:3,
    total_time:0,
    average_time:0
}

Check the stats of a particular stream:

stats.streams['STREAM_ID']

{
    bytes_received:22535,
    bytes_sent:13362,
    bytes_transferred:35897,
    packets_received:73,
    packets_sent:91,
    packets_transferred:164,
    start_time:Mon, 02 May 2011 12:04:54 GMT,
    end_time:Mon, 02 May 2011 12:06:57 GMT,
    condition:'item-not-found',
    device_type:'iphone',
    from:'abc@directi.com'
}

Check the stats of a particular session:

stats.sessions['SESSION_ID']

{
    bytes_received:22535,
    bytes_sent:13362,
    bytes_transferred:35897,
    packets_received:73,
    packets_sent:91,
    packets_transferred:164,
    start_time:Mon, 02 May 2011 12:04:54 GMT,
    end_time:Mon, 02 May 2011 12:06:57 GMT
}

Check the average time of a stream (aggregated over all streams):

stats.streams.all.average_time

00:03:43

Check the average time of a session (aggregated over all sessions):

stats.sessions.all.average_time

00:03:43

Check the stats by jids:

stats.jids.all

{
    active:3, /* Currently active unique jids */
    total:3   /* Total unique jids */
} 

Check the stats of a unique jid

stats.jids['jid@xmmp.com']

{
    running:3, /* Active streams */
    total:3, 
    total_time:0,
    average_time:0,

    bytes_received:22535,
    bytes_sent:13362,
    bytes_transferred:35897,
    packets_received:73,
    packets_sent:91,
    packets_transferred:164,

    streams.active: {
          streamid: stream-object
    },
    streams.terminated: {
          streamid: stream-object
    },

    last_created: Mon, 02 May 2011 12:04:54 GMT,
    last_terminated: null

}

Check the stats by domains: stats.domains.all

{
    active:3,
    total:3
} 

Check the stats of a unique domain

stats.domains['xmmp.com']

{
    running:3,
    total:3,
    total_time:0,
    average_time:0,

    bytes_received:22535,
    bytes_sent:13362,
    bytes_transferred:35897,
    packets_received:73,
    packets_sent:91,
    packets_transferred:164,

    streams.active: {
          streamid: stream-object
    }
    streams.terminated: {
          streamid: stream-object
    }

}

Check the stats by a device_type set the ua attribute as device type in session creation request. supported ua = 'iphone', 'blackberry', 'android', 'desktop'.

stats.device_type['iphone']

{
    running:3,
    total:3,
    total_time:0,
    average_time:0,

    bytes_received:22535,
    bytes_sent:13362,
    bytes_transferred:35897,
    packets_received:73,
    packets_sent:91,
    packets_transferred:164,

    streams.active: {
          streamid: stream-object
    }
    streams.terminated: {
          streamid: stream-object
    }

}

Check system stats stats.cpu.uptime stats.cpu.loadavg stats.cpu.totalmem stats.cpu.freemem stats.cpu.cpus

Check process stats stats.process.pid stats.process.memory_usage