/symple-server

Symple real time messaging and presence server using Node.js, Socket.IO and Redis

Primary LanguageJavaScript

Symple Server

The Symple Node.js server is a real time messaging server built on top of socket.io and redis for creating blazing fast messaging applications quickly and easily. Use cases include chat, sms, media streaming, and games that run in the web browser, desktop, or on mobile devices.

What is Symple?

Symple is an unrestrictive real time messaging and presence protocol that implements the minimum number of features required to build full fledged messaging applications with security, flexibility, performance and scalability in mind. These features include:

  • Session sharing with any backend (via Redis)
  • User rostering and presence
  • Media streaming (via WebRTC, see demo)
  • Scoped messaging ie. direct, user and group scope
  • Real-time commands and events
  • Real-time forms

Installation

Install Redis Note that Redis is optional, but required if you want to share secure sessions. If you're using Ubuntu just type:

sudo apt-get install redis-server

Install Symple from npm:

npm install symple

# use the --save flag to automatically add Symple to your package.json dependencies
# npm install symple --save

Done.

Usage

To get started straight away fire up the default server by typing:

node server

# or using npm
# npm start

The server.js file in the root directory of the repo provides an example of how to include the Symple server in your own code:

// include Symple
var Symple = require('symple');

// instantiate the Symple server
var sy = new Symple();

// load a config file
sy.loadConfig(__dirname + "/symple.json");

// initialize the server
sy.init();

// access socket.io instance methods if required
// sy.io.use(function(socket, next) { });

// access HTTP/S server instance methods if required
// sy.http ...

// access Redis publish/subscribe client instance methods
// sy.pub ...
// sy.sub ...

console.log('Symple server listening on port ' + sy.config.port);

See the configuration options below for a list of available options.

Once the server is up and running you need a client to connect to it. There are a number of options here in the following languages:

Configuration

To configure the server just modify symple.json as needed:

{
  /*
    The port to listen on (default: 4500).
    If `process.env.PORT` is set, the env value will be used instead.
    Port 443 should always be used for SSL.
  */
  "port" : 4500,  /* 443 */

  /*
    Session time-to-live in minutes (default: 15 minutes)
    This is the duration of time before sessions expire after the client disconnects.
    If set to `-1` the session will never expire.
  */
  "sessionTTL" : 15,

  /* Enable or disable authentication */
  "authentication" : true,

  /*
    Redis configuration
    Redis must be available if using `authentication = true`
  */
  "redis" : {
    "host" : "localhost",
    "port" : 6379,
    "password" : "redispwd"
  },

  /* SSL configuration */
  "ssl" : {
    "enabled" : false,
    "key" : "ssl/symple.key",
    "cert" : "ssl/symple.crt"
  }
}

API Reference

Symple

Symple server class.

Kind: global class
Access: public

new Symple(config)

Param Type Description
config Object optional confguration object (see config.json)
config.port string the port to listen on
config.redis Object redis configuration
config.ssl Object ssl configuration
config.sessionTTL number session timeout value
config.authentication boolean enable/disable authentication

symple.loadConfig(filepath)

Load configuration from a file.

Kind: instance method of Symple
Access: public

Param Type Description
filepath string absolute path to config.json

symple.init()

Initialize the Symple server.

Kind: instance method of Symple
Access: public

symple.shutdown()

Shutdown the Symple server.

Kind: instance method of Symple
Access: public

symple.broadcast(socket, message)

Broadcast a message over the given socket.

Kind: instance method of Symple
Access: public

Param Type Description
socket Socket client socket
message Object message to send

symple.getSession(token, fn)

Get a peer session by it's token.

Kind: instance method of Symple
Access: public

Param Type Description
token Object address string
fn function callback function

symple.touchSession(token, fn)

Touch a peer session by it's token and extend it's lifetime by (config.sessionTTL) minutes.

Kind: instance method of Symple
Access: public

Param Type Description
token Object address string
fn function callback function

symple.parseAddress(str)

Parse a peer address with the format: user@group/id

Kind: instance method of Symple
Access: public

Param Type Description
str Object address string

Contributing

Contributions are always welcome :)

  1. Fork it
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create new Pull Request

Contact

For more information check out the Symple homepage: http://sourcey.com/symple/ For bugs or issues please use the Github issue tracker: https://github.com/sourcey/symple-server-node/issues