@sockethub/platform-irc 4.0.0-alpha.3 → 4.0.0-alpha.6

package/index.js

@@ -1,701 +0,0 @@
-/**
- * This is a platform for Sockethub implementing IRC functionality.
- *
- * Developed by Nick Jennings (https://github.com/silverbucket)
- *
- * Sockethub is licensed under the LGPLv3.
- * See the LICENSE file for details.
- *
- * The latest version of this module can be found here:
- *   git://github.com/sockethub/sockethub.git
- *
- * For more information about Sockethub visit http://sockethub.org/.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
- */
-
-if (typeof (NetSocket) !== 'object') {
-  net = require('net');
-}
-if (typeof (TlsSocket) !== 'object') {
-  tls = require('tls');
-}
-if (typeof (IrcSocket) !== 'object') {
-  IrcSocket = require('irc-socket-sasl');
-}
-if (typeof (IRC2AS) !== 'object') {
-  IRC2AS = require('@sockethub/irc2as');
-}
-
-
-/**
- * @class IRC
- * @constructor
- *
- * @description
- * Handles all actions related to communication via. the IRC protocol.
- *
- * Uses the `irc-factory` node module as a base tool for interacting with IRC.
- *
- * {@link https://github.com/ircanywhere/irc-factory}
- *
- * @param {object} cfg a unique config object for this instance // TODO LINK
- */
-function IRC(cfg) {
-  cfg = (typeof cfg === 'object') ? cfg : {};
-  this.debug = cfg.debug;
-  this.sendToClient = cfg.sendToClient;
-  this.updateActor = cfg.updateActor;
-  this.__forceDisconnect = false;
-  this.__clientConnecting = false;
-  this.__client = undefined;
-  this.__jobQueue = []; // list of handlers to confirm when message delivery confirmed
-  this.__channels = new Set();
-  this.__handledActors = new Set();
-}
-
-/**
- * Property: schema
- *
- * @description
- * JSON schema defining the types this platform accepts.
- *
- *
- * In the below example, Sockethub will validate the incoming credentials object
- * against whatever is defined in the `credentials` portion of the schema
- * object.
- *
- *
- * It will also check if the incoming AS object uses a type which exists in the
- * `types` portion of the schema object (should be an array of type names).
- *
- * * **NOTE**: For more information on using the credentials object from a client,
- * see [Sockethub Client](https://github.com/sockethub/sockethub/wiki/Sockethub-Client)
- *
- * Valid AS object for setting IRC credentials:
- * @example
- *
- *  {
- *    type: 'credentials',
- *    context: 'irc',
- *    actor: {
- *      id: 'testuser@irc.host.net',
- *      type: 'person',
- *      name: 'Mr. Test User',
- *      userName: 'testuser'
- *    },
- *    object: {
- *      type: 'credentials',
- *      server: 'irc.host.net',
- *      nick: 'testuser',
- *      password: 'asdasdasdasd',
- *      port: 6697,
- *      secure: true,
- *      sasl: true
- *    }
- *  }
- */
-IRC.prototype.schema = {
-  "name": "irc",
-  "version": require('./package.json').version,
-  "messages" : {
-    "required": [ 'type' ],
-    "properties": {
-      "type": {
-        "enum": [ 'connect', 'update', 'join', 'leave', 'send', 'query', 'announce' ]
-      }
-    }
-  },
-  "credentials" : {
-    "required": [ 'object' ],
-    "properties": {
-      // TODO platforms shouldn't have to define the actor property
-      //  if they don't want to, just credential specifics
-      "actor": {
-        "type": "object",
-        "required": [ "id" ]
-      },
-      "object": {
-        "type": "object",
-        "required": [ 'type', 'nick', 'server' ],
-        "additionalProperties": false,
-        "properties" : {
-          "type": {
-            "type": "string"
-          },
-          "nick" : {
-            "type": "string"
-          },
-          "username" : {
-            "type": "string"
-          },
-          "password" : {
-            "type": "string"
-          },
-          "server" : {
-            "type": "string"
-          },
-          "port" : {
-            "type": "number"
-          },
-          "secure": {
-            "type": "boolean"
-          },
-          "sasl": {
-            "type": "boolean"
-          }
-        }
-      }
-    }
-  }
-};
-
-
-IRC.prototype.config = {
-  persist: true,
-  requireCredentials: [ 'connect', 'update' ],
-  initialized: false
-};
-
-/**
- * Function: connect
- *
- * Conenct to an IRC server.
- *
- * @param {object} job activity streams object
- * @param {object} credentials credentials object
- * @param {object} done callback when job is done
- */
-
-IRC.prototype.connect = function (job, credentials, done) {
-  this.__getClient(job.actor.id, credentials, (err, client) => {
-    if (err) { return done(err); }
-    return done();
-  });
-};
-
-/**
- * Function: join
- *
- * Join a room or private conversation.
- *
- * @param {object} job activity streams object // TODO LINK
- * @param {object} done callback when job is done // TODO LINK
- *
- * @example
- *
- * {
- *   context: 'irc',
- *   type: 'join',
- *   actor: {
- *     id: 'slvrbckt@irc.freenode.net',
- *     type: 'person',
- *     name: 'slvrbckt'
- *   },
- *   target: {
- *     id: 'irc.freenode.net/a-room',
- *     type: 'room',
- *     name: '#a-room'
- *   },
- *   object: {}
- * }
- *
- */
-IRC.prototype.join = function (job, done) {
-  this.debug('join() called for ' + job.actor.id);
-  this.__getClient(job.actor.id, false, (err, client) => {
-    if (err) { return done(err); }
-    if (this.__channels.has(job.target.name)) {
-      this.debug(`channel ${job.target.name} already joined`);
-      return done();
-    }
-    // join channel
-    this.__jobQueue.push(() => {
-      this.__hasJoined(job.target.name);
-      done();
-    });
-    this.debug('sending join ' + job.target.name);
-    client.raw(['JOIN', job.target.name]);
-    client.raw('PING ' + job.actor.name);
-  });
-};
-
-/**
- * Function leave
- *
- * Leave a room or private conversation.
- *
- * @param {object} job activity streams object // TODO LINK
- * @param {object} done callback when job is done // TODO LINK
- *
- * @example
- * {
- *   context: 'irc',
- *   type: 'leave',
- *   actor: {
- *     id: 'slvrbckt@irc.freenode.net',
- *     type: 'person',
- *     name: 'slvrbckt'
- *   },
- *   target: {
- *     id: 'irc.freenode.net/remotestorage',
- *     type: 'room',
- *     name: '#remotestorage'
- *   },
- *   object: {}
- * }
- *
- */
-IRC.prototype.leave = function (job, done) {
-  this.debug('leave() called for ' + job.actor.name);
-  this.__getClient(job.actor.id, false, (err, client) => {
-    if (err) { return done(err); }
-    // leave channel
-    this.__hasLeft(job.target.name);
-    client.raw(['PART', job.target.name]);
-    done();
-  });
-};
-
-/**
- * Function: send
- *
- * Send a message to a room or private conversation.
- *
- * @param {object} job activity streams object // TODO LINK
- * @param {object} done callback when job is done // TODO LINK
- *
- * @example
- *
- *  {
- *    context: 'irc',
- *    type: 'send',
- *    actor: {
- *      id: 'slvrbckt@irc.freenode.net',
- *      type: 'person',
- *      name: 'Nick Jennings',
- *      userName: 'slvrbckt'
- *    },
- *    target: {
- *      id: 'irc.freenode.net/remotestorage',
- *      type: 'room',
- *      name: '#remotestorage'
- *    },
- *    object: {
- *      type: 'message',
- *      content: 'Hello from Sockethub!'
- *    }
- *  }
- *
- */
-IRC.prototype.send = function (job, done) {
-  this.debug('send() called for ' + job.actor.id + ' target: ' + job.target.id);
-  this.__getClient(job.actor.id, false, (err, client) => {
-    if (err) { return done(err); }
-
-    if (typeof job.object.content !== 'string') {
-      return done('cannot send message with no object.content');
-    }
-
-    let msg = job.object.content.trim();
-    if (msg.indexOf('/') === 0) {
-      // message intented as command
-      msg += ' ';
-      const cmd = msg.substr(0, msg.indexOf(' ')).substr(1).toUpperCase(); // get command
-      msg = msg.substr(msg.indexOf(' ') + 1).replace(/\s\s*$/, ''); // remove command from message
-      if (cmd === 'ME') {
-        // handle /me messages uniquely
-        job.object.type = 'me';
-        job.object.content = msg;
-      } else if (cmd === 'NOTICE') {
-        // attempt to send as raw command
-        job.object.type = 'notice';
-        job.object.content = msg;
-      }
-    } else {
-      job.object.content = msg;
-    }
-
-    if (job.object.type === 'me') {
-      // message intended as command
-      // jsdoc does not like this octal escape sequence but it's needed for proper behavior in IRC
-      // so the following line needs to be commented out when the API doc is built.
-      // investigate:
-      // https://github.com/jsdoc2md/jsdoc-to-markdown/issues/197#issuecomment-976851915
-      const message = '\001ACTION ' + job.object.content + '\001';
-      client.raw('PRIVMSG ' + job.target.name + ' :' + message);
-    } else if (job.object.type === 'notice') {
-      // attempt to send as raw command
-      client.raw('NOTICE ' + job.target.name + ' :' + job.object.content);
-    } else if (this.__isJoined(job.target.name)) {
-      client.raw('PRIVMSG ' + job.target.name + ' :' + job.object.content);
-    } else {
-      return done("cannot send message to a channel of which you've not first joined.");
-    }
-    this.__jobQueue.push(done);
-    client.raw('PING ' + job.actor.name);
-  });
-};
-
-/**
- * Function: update
- *
- * Indicate a change (ie. room topic update, or nickname change).
- *
- * @param {object} job activity streams object // TODO LINK
- * @param {object} done callback when job is done // TODO LINK
- *
- * @example change topic
- *
- * {
- *   context: 'irc',
- *   type: 'update',
- *   actor: {
- *     id: 'slvrbckt@irc.freenode.net',
- *     type: 'person',
- *     name: 'Nick Jennings',
- *     userName: 'slvrbckt'
- *   },
- *   target: {
- *     id: 'irc.freenode.net/a-room',
- *     type: 'room',
- *     name: '#a-room'
- *   },
- *   object: {
- *     type: 'topic',
- *     content: 'New version of Socekthub released!'
- *   }
- * }
- *
- * @example change nickname
- *  {
- *    context: 'irc'
- *    type: 'udpate',
- *    actor: {
- *      id: 'slvrbckt@irc.freenode.net',
- *      type: 'person',
- *      name: 'slvrbckt'
- *    },
- *    object: {
- *      type: "address",
- *    },
- *    target: {
- *      id: 'cooldude@irc.freenode.net',
- *      type: 'person',
- *      name: cooldude
- *    }
- *  }
- */
-IRC.prototype.update = function (job, credentials, done) {
-  this.debug('update() called for ' + job.actor.id);
-  this.__getClient(job.actor.id, false, (err, client) => {
-    if (err) { return done(err); }
-    if (job.object.type === 'address')  {
-      this.debug('changing nick from ' + job.actor.name + ' to ' + job.target.name);
-      this.__handledActors.add(job.target.id);
-      this.__jobQueue.push((err) => {
-        if (err) {
-          this.__handledActors.delete(job.target.id);
-          return done(err);
-        }
-        credentials.object.nick = job.target.name;
-        credentials.actor.id = `${job.target.name}@${credentials.object.server}`;
-        credentials.actor.name = job.target.name;
-        this.updateActor(credentials);
-        done();
-      });
-      // send nick change command
-      client.raw(['NICK', job.target.name]);
-    } else if (job.object.type === 'topic') {
-      // update topic
-      this.debug('changing topic in channel ' + job.target.name);
-      this.__jobQueue.push(done);
-      client.raw(['topic', job.target.name, job.object.content]);
-    } else {
-      return done(`unknown update action.`);
-    }
-    client.raw('PING ' + job.actor.name);
-  });
-};
-
-/**
- * Function: query
- *
- * Indicate an intent to query something (e.g. get a list of users in a room).
- *
- * @param {object} job activity streams object // TODO LINK
- * @param {object} done callback when job is done // TODO LINK
- *
- * @example
- *
- *  {
- *    context: 'irc',
- *    type: 'query',
- *    actor: {
- *      id: 'slvrbckt@irc.freenode.net',
- *      type: 'person',
- *      name: 'Nick Jennings',
- *      userName: 'slvrbckt'
- *    },
- *    target: {
- *      id: 'irc.freenode.net/a-room',
- *      type: 'room',
- *      name: '#a-room'
- *    },
- *    object: {
- *      type: 'attendance'
- *    }
- *  }
- *
- *
- *  // The above object might return:
- *  {
- *    context: 'irc',
- *    type: 'query',
- *    actor: {
- *      id: 'irc.freenode.net/a-room',
- *      type: 'room',
- *      name: '#a-room'
- *    },
- *    target: {},
- *    object: {
- *      type: 'attendance'
- *      members: [
- *        'RyanGosling',
- *        'PeeWeeHerman',
- *        'Commando',
- *        'Smoochie',
- *        'neo'
- *      ]
- *    }
- *  }
- *
- */
-IRC.prototype.query = function (job, done) {
-  this.debug('query() called for ' + job.actor.id);
-  this.__getClient(job.actor.id, false, (err, client) => {
-    if (err) { return done(err); }
-
-    if (job.object.type === 'attendance') {
-      this.debug('query() - sending NAMES for ' + job.target.name);
-      client.raw(['NAMES', job.target.name]);
-      done();
-    } else {
-      done("unknown 'type' '" + job.object.type + "'");
-    }
-  });
-};
-
-
-IRC.prototype.cleanup = function (done) {
-  this.debug('cleanup() called');
-  this.__forceDisconnect = true;
-  if (typeof this.__client === 'object') {
-    if (typeof this.__client.end === 'function') {
-      this.__client.end();
-    }
-  }
-  this.initialized = false;
-  delete this.__client;
-  return done();
-};
-
-
-
-//
-// Private methods
-//
-
-
-IRC.prototype.__isJoined = function (channel) {
-  if (channel.indexOf('#') === 0) {
-    // valid channel name
-    return this.__channels.has(channel);
-  } else {
-    // usernames are always OK to send to
-    return true;
-  }
-};
-
-
-IRC.prototype.__hasJoined = function (channel) {
-  this.debug('joined ' + channel);
-  // keep track of channels joined
-  if (! this.__channels.has(channel)) {
-    this.__channels.add(channel);
-  }
-};
-
-
-IRC.prototype.__hasLeft = function (channel) {
-  this.debug('left ' + channel);
-  // keep track of channels left
-  if (this.__channels.has(channel)) {
-    this.__channels.delete(channel);
-  }
-};
-
-
-IRC.prototype.__getClient = function (key, credentials, cb) {
-  this.debug('getClient called, connecting: ' + this.__clientConnecting);
-  if (this.__client) {
-    this.__handledActors.add(key);
-    return cb(null, this.__client);
-  } else if (this.__clientConnecting) {
-    // client is in the process of connecting, wait
-    setTimeout(function (_cb) {
-      if (this.__client) {
-        this.debug(`resolving delayed getClient call for ${key}`);
-        this.__handledActors.add(key);
-        return _cb(null, this.__client);
-      } else {
-        return cb('failed to get irc client, please try again.');
-      }
-    }.bind(this, cb), 30000);
-    return;
-  }
-
-  if (! credentials) {
-    return cb('no client found, and no credentials specified. you must connect first');
-  } else {
-    this.__connect(key, credentials, (err, client) => {
-      if (err) {
-        this.initialized = false;
-        return cb(err);
-      }
-      this.__handledActors.add(key);
-      this.__client = client;
-      this.__registerListeners(credentials.object.server);
-      this.initialized = true;
-      return cb(null, client);
-    });
-  }
-};
-
-
-IRC.prototype.__connect = function (key, credentials, cb) {
-  this.__clientConnecting = true;
-  const is_secure = (typeof credentials.object.secure === 'boolean') ?
-    credentials.object.secure : true;
-
-  const module_options = {
-    username: credentials.object.username || credentials.object.nick,
-    nicknames: [ credentials.object.nick ],
-    server: credentials.object.server || 'irc.libera.chat',
-    realname: credentials.actor.name || credentials.object.nick,
-    port: (credentials.object.port) ?
-      parseInt(credentials.object.port, 10) : (is_secure) ? 6697 : 6667,
-    debug: console.log
-  };
-  if (is_secure) {
-    module_options.connectOptions = { rejectUnauthorized: false };
-  }
-  if (credentials.object.sasl) {
-    module_options.saslPassword = credentials.object.password;
-    module_options.capabilities = { requires: [ "sasl" ] };
-  }
-
-  this.debug('attempting to connect to ' + module_options.server + ':' + module_options.port +
-    ` transport: ${is_secure?'secure':'clear'} sasl: ${credentials.object.sasl}`);
-
-  const client = new IrcSocket(module_options, is_secure ? tls : net);
-
-  const __forceDisconnect = (err) => {
-    this.__forceDisconnect = true;
-    this.__clientConnecting = false;
-    if ((client) && (typeof client.end === 'function')) {
-      client.end();
-    }
-    if ((this.__client) && (typeof this.__client.end === 'function')) {
-      this.__client.end();
-    }
-    cb(err);
-  };
-
-  client.once('error', (err) => {
-    this.debug(`irc client 'error' occurred. `, err);
-    __forceDisconnect('error connecting to server.');
-  });
-
-  client.once('close', () => {
-    this.debug(`irc client 'close' event fired.`);
-    __forceDisconnect('connection to server closed.');
-  });
-
-  client.once('timeout', () => {
-    this.debug('timeout occurred, force-disconnect');
-    __forceDisconnect('connection timeout to server.');
-  });
-
-  client.connect().then((res) => {
-    if (res.isFail()) {
-      return cb(`unable to connect to server: ${res.fail()}`);
-    }
-    const capabilities = res.ok();
-    this.__clientConnecting = false;
-    if (this.__forceDisconnect) {
-      client.end();
-      return cb('force disconnect active, aborting connect.');
-    } else {
-      this.debug(`connected to ${module_options.server} capabilities: `, capabilities);
-      return cb(null, client);
-    }
-  });
-};
-
-
-IRC.prototype.__completeJob = function (err) {
-  this.debug(`completing job, queue count: ${this.__jobQueue.length}`);
-  const done = this.__jobQueue.shift();
-  if (typeof done === 'function') {
-    done(err);
-  } else {
-    this.debug('WARNING: job completion event received with an empty job queue.');
-  }
-};
-
-
-IRC.prototype.__registerListeners = function (server) {
-  this.irc2as = new IRC2AS({ server: server });
-  this.__client.on('data', (data) => {
-    this.irc2as.input(data);
-  });
-
-  this.irc2as.events.on('incoming', (asObject) => {
-    if ((typeof asObject.actor === 'object') &&
-        (typeof asObject.actor.name === 'string') &&
-        (this.__handledActors.has(asObject.actor.id))) {
-      this.__completeJob();
-    } else {
-      this.debug(
-        'calling sendToClient for ' + asObject.actor.id, [...this.__handledActors.keys()]);
-      this.sendToClient(asObject);
-    }
-  });
-
-  this.irc2as.events.on('unprocessed', (string) => {
-    this.debug('unprocessed irc message:> ' + string);
-  });
-
-  // The generated eslint error expects that the `error` event is propagating an Error object
-  // however for irc2as this event delivers an AS object of type `error`.
-  // eslint-disable-next-line security-node/detect-unhandled-event-errors
-  this.irc2as.events.on('error', (asObject) => {
-    this.debug('message error response ' + asObject.object.content);
-    this.__completeJob(asObject.object.content);
-  });
-
-  this.irc2as.events.on('pong', (timestamp) => {
-    this.debug('received PONG at ' + timestamp);
-    this.__completeJob();
-  });
-
-  this.irc2as.events.on('ping', (timestamp) => {
-    this.debug('received PING at ' + timestamp);
-    this.__client.raw('PONG');
-  });
-};
-
-module.exports = IRC;