Symple Server

Realtime messaging and presence server built on Socket.IO.

Part of the Symple ecosystem:

• symple-client — JavaScript client (browser & Node.js)
• symple-client-ruby — Ruby/Rails server-side emitter

Features

• Presence — peer online/offline status broadcasting
• Scoped messaging — direct (peer-to-peer), user-level, room-level, or global broadcast
• Dynamic rooms — clients can join and leave rooms at runtime
• Token authentication — session validation via Redis (or anonymous mode)
• Horizontal scaling — optional Redis pub/sub adapter for multi-instance deployments
• SSL/TLS — optional HTTPS support

Quick Start

git clone https://github.com/sourcey/symple-server.git
cd symple-server
npm install
npm start

The server listens on port 4500 by default. No Redis required — it runs in single-instance mode out of the box.

Configuration

All configuration is via environment variables (loaded from .env via dotenv). Copy .env.example to .env to get started.

| Variable | Default | Description | |---|---|---| | PORT | 4500 | Port to listen on (also SYMPLE_PORT) | | SYMPLE_SESSION_TTL | -1 | Session TTL in minutes (-1 = no expiry) | | SYMPLE_AUTHENTICATION | false | Require token auth (needs Redis) | | SYMPLE_DYNAMIC_ROOMS | true | Allow clients to join/leave rooms | | SYMPLE_REDIS_URL | — | Redis connection URL (enables Redis features) | | SYMPLE_REDIS_HOST | — | Redis host (alternative to URL) | | SYMPLE_REDIS_PORT | — | Redis port (alternative to URL) | | SYMPLE_CORS_ORIGINS | * (allow all) | Comma-separated origins or * | | SYMPLE_CORS_METHODS | GET,POST | Allowed HTTP methods | | SYMPLE_CORS_CREDENTIALS | — | Enable credentials (true/false) | | SYMPLE_SSL_ENABLED | false | Enable HTTPS | | SYMPLE_SSL_KEY | — | Path to SSL key file | | SYMPLE_SSL_CERT | — | Path to SSL certificate file |

Redis

Redis is optional. Without it, the server runs in single-instance mode with in-memory Socket.IO. Set SYMPLE_REDIS_URL to enable:

• Horizontal scaling — multiple server instances via the @socket.io/redis-adapter
• Token authentication — session lookup at symple:session:<token>
• Server-side emission — push messages from Ruby/Rails via symple-client-ruby

Authentication

When SYMPLE_AUTHENTICATION=true, clients must provide user and token in the Socket.IO handshake auth. The server looks up the session in Redis at symple:session:<token> and merges it with the auth data.

When SYMPLE_AUTHENTICATION=false (default), clients only need to provide user.

Message Routing

Messages are routed based on the to field:

| to value | Behavior | |---|---| | Undefined | Broadcast to joined rooms (or globally if dynamicRooms is off) | | "user\|id" | Direct message to a specific peer | | ["room1", "room2"] | Broadcast to multiple rooms |

Programmatic Usage

const Symple = require('./lib/symple');
const { createConfig } = require('./config');

const config = createConfig();
const server = new Symple(config);

// Override the post-auth hook
server.onAuthorize = function(socket) {
  console.log('Peer connected:', socket.peer.name);
};

server.init();

Debug Logging

Enable debug output with:

DEBUG=symple:* npm start

License

MIT