hybrid-ircd

A combination IRC daemon / client library for Node.js

WARNING:

hybrid-ircd is still under development, and not ready for general use yet!

Table of Contents

• Installation
• Introduction
• Server config
• Client config
• Client scripting
• Todo

Installation

npm install @fc3/hybrid-ircd

Introduction

hybrid-ircd is both an IRC daemon, and an IRC client, all rolled into one module. It's written in TypeScript.

Starting your own IRC server is easy:

var {Server} = require('@fc3/hybrid-ircd');

var server = new Server();

server.listen();

// Server is now listening on port 6667!

So is spawning an IRC client:

var {Client} = require('@fc3/hybrid-ircd');

var client = new Client('0xfc3');

client.connectToServer('irc.myserver.com', function(error) {
    if (error) {
        throw error;
    }

    // We're now successfully connected! Yay!

    client.joinChannel('#sysops', function(error) { // JOIN #sysops
        if (error) {
            throw error;
        }

        client.sendMessageToChannel('I have returned!', channel); // PRIVMSG #sysops :I have returned!
    });
});

Server Config

Technically, you don't need to supply any additional options when you create a new server instance:

const {Server} = require('@fc3/hybrid-ircd');

(new Server()).listen();

The above example creates a new server instance, using the default settings, and has it start listening on port 6667.

The default settings are as follows:

|Setting name |Default value |Meaning | |----------------------------|-----------------------------------------------------------------|------------------------------------------------------------------------------------| |name |"Hybrid" |Displayed to clients upon connecting | |hostname |OS.hostname() |Identifies the server to clients and other servers | |port |6667 |The port the server should listen on | |motd |null |The MOTD to show to connecting clients |resolve_hostnames |true |Whether to reverse-resolve client hostnames; when false the IP address is used | |channel_modes |"biklmnpstv" |The subset of supported channel modes that clients can set | |user_modes |"iosw" |The subset of supported user modes that clients can set | |max_channels |20 |The maximum number of channels a client can join | |max_targets |20 |The maximum number of targets a client can specify for a message | |max_bans |60 |The maximum number of ban masks allowed for a given channel | |max_parameters |32 |The maximum number of parameters allowed for a given command | |max_nick_length |32 |The maximum allowed client nick length | |max_topic_length |307 |The maximum allowed channel topic length |

You will probably want to override these settings. To do so, you can supply an options object to the Server constructor:

var {Server} = require('@fc3/hybrid-ircd');

var server = new Server({
    name:          'hybrid',
    hostname:      'irc.myserver.com',
    port:          1234,
    motd:          'Welcome to Burning Garden's IRC server. Be good, and don't be bad!'
    channel_modes: 'bmnpsq',
    user_modes:    'ars'
});

In addition to specifying the port in the options object, you can also just pass it to server.listen() directly:

server.listen(1234);

A list of hybrid-ircd's supported channel modes, and their meanings, can be found here.

A list of hybrid-ircd's supported user modes, and their meanings, can be found here.

Client Config

The amount of information needed when instantiating a new client is minimal. In fact, you could just instantiate a client directly, and call connectToServer() without supplying any additional information:

var {Client} = require('@fc3/hybrid-ircd');
var client = new Client(); // The default nick, "hybrid", will be used.

client.connectToServer(function(error) { // Will attempt to connect to localhost:6667
    // Do something
});

But I'm guessing you want more flexibility than that. Not a problem. You can override the default nick for your client by passing it directly to the Client constructor:

var Client = require('@fc3/hybrid-ircd');
var client = new Client('0xfc3'); // Now the nick "0xfc3" will be used when connecting to servers

You can also specify additional options when connecting to a specific server, in the form of an options object:

var Client = require('@fc3/hybrid-ircd');
var client = new Client();

var options = {
    hostname: 'irc.myserver.com',
    port:     6669,
    nick:     '0xfc3',
    username: '0xfc3',
    realname: 'Test User'
};

client.connectToServer(options, function(error) {
    // Do something
});

This makes it easy to specify different values for different server connections using the same client.

The default values for the options object when connecting to a server is as follows:

|Setting name |Default value |Meaning | |--------------|---------------|----------------------------------------------------------------------| |nick |"hybrid" |Identifies your client on the network, unique to your user | |username |"hybrid" |Identifies your client on the network, not necessarily unique to you | |realname |"Hybrid" |Your favorite character on your favorite TV show | |hostname |"localhost" |The remote hostname of the server to connect to | |port |6667 |The remote port of the server to connect to |

Client scripting

If you're writing an IRC client using hybrid-ircd, you probably want some way to programmatically interact with the IRC networks you're connecting to.

Here's an example of a simple bot written using Client, just to serve as an illustration of what's possible. More comprehensive documentation can be found below.

var {Client} = require('@fc3/hybrid-ircd');
var client = new Client();

client.connectToServer('irc.myserver.com', function(error) {
    if (error) {
        throw error;
    }

    // Connect to some initial channels:
    client.joinChannel('#sysops');
    client.joinChannel('#zeldafans');
    client.joinChannel('#seriousbusiness');
});

client.on('message', function(message) {
    var nick = message.getNick();

    if (!nick) {
        // Some messages don't have nicks; ie, server notice messages.
        return;
    }

    // Reply to the message we received:
    client.respondToMessage(message, 'What in the world are you talking about?');

    client.sendWhoisQueryForNick(nick, function(error, user) {
        if (error) {
            throw error;
        }

        // Crawl our way throughout the network:
        user.getChannelNames().forEach(client.joinChannel, client);
    });
});

Todo

There's still a fair amount of work I need to do. Namely:

• SSL support
• Services (ie, NickServe)
• Actual server <-> server connections
• Authentication