irc-posts-cache-client

[wip/experiemental] irc-posts-cache-client

THIS MODULE IS EXPERIMENTAL. IT MOSTLY WORKS, BUT MAY NOT BE GENERICIZED ENOUGH FOR WIDE APOPTION YET AND CONTAINS MINIMAL VALIDATION/PRODUCTION HARDENING. If you're interested in using it, star it on GitHub or open an issue. If you want to integrate it into your IRC app, take a look at the /test/mocks directory to see what this module expects.

This module is meant to be a simple, configurable, ephemeral backend plugin that adds the ability to create and broadcast "posts" in standard IRC (chat)server implementations. It utilizes Redis and LevelDB, which you'll need to install separately.

You'll want to hook this module up to a custom command that you add to your standard IRC server (RFC1459, etc). This module returns a client conencted to a simple ephemeral cache (Redis and LevelDB). That means you'll need to do your own thing for surfacing the posts in your chat UI.

This module is agnostic about the structure of the post objects you pass into the posts cache, as long as they are well-formed JSON objects.

This module is also agnostic about your user(s) as well. It tracks (and de-dupes) counts on posts (upvotes, downvotes, flags) against whatever simple unique identifier you pass in as a user id.

If you want to fetch posts by alogorithmic sort based on upvotes and downvotes, then minimally the post objects you pass into postsClient.posts.add() should contain a counts object which in turn contains upvotes and downvotes properties, each with a numeric value. For now, the only agorithmic sort available is the level news top posts algorithm, but later on if there's interest this module can be customized to utilize any algorithm that you configure.

Usage

This module has been left somewhat agnostic about how you use it so that it is flexible if you want to get creative. The client's public API consists of a number of methods and objects for you to play with, but for a basic implementation you really only need a few methods. Again, see the /test directory for more details.

const PostsCacheClient = require('irc-posts-cache-client')
// init the module:
const postsClient = PostsCacheClient(server, config) // config notes below

The server property is your irc server that this module will expect to contain the following methods:

server.normalizeName() // a sync op that might .toLowerCase() channel names
server.ircProtocol.validations.validChannel // where validChannel is a regex
server.channels.find(channelName) // where find() is a sync operation
server.channels.join(user, channelName) // a sync op

If you don't need/want to enforce the rule that a user must be able to join() a channel to post to it, you can call with a third argument postsClient.posts.add('', postObject, {bypassChannelAuth: true})

Configuration

When you init this module, you may override the config following properties (default config values are below):

config = {
  /*
  Rules: Alphanumeric. Must not contain `#`.
  TODO: set up some validation for this property.
  */
  cacheKeyPrefix: 'postscache',

  /*
  Optional: Dedupe posts in a single channel by post field specified as a string.
  Will dedupe field by type and value.
  Note: if field is missing from post object passed into posts.add(), no deduping will be attempted and post will be cached.
  */
  dedupeBy: null,

  levelDB: {
    path: './../db',
    retry: false,
    defaultTTL: 1000 * 60 * 60 * 24 * 30,
    ttlCheckFrequency: 3000
  },

  redis: {
    port: 6379,
    host: '127.0.0.1',
    debugMode: false
  },

  posts: {
    limitPerChannel: 100,
    fetchedBatchTTL: 3000 // ms
  }
}

API

For a basic implementation, the only methods you need to care about are below. Again, you'll find sample usage of each inside the /test dir:

postsClient.posts.add()
postsClient.posts.fetch()
postsClient.posts.upvotePost()
postsClient.posts.downvotePost()
postsClient.posts.flagPost()