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:

• JavaScript: https://github.com/sourcey/symple-client
• Ruby: https://github.com/sourcey/symple-client-ruby
• C++: https://github.com/sourcey/libsourcey/tree/master/src/symple

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

• Symple
  • new Symple(config)
  • .loadConfig(filepath)
  • .init()
  • .shutdown()
  • .broadcast(socket, message)
  • .getSession(token, fn)
  • .touchSession(token, fn)
  • .parseAddress(str)

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