msterle / kalm.js

The socket manager

Kalm

The Socket Manager

---

• Easy-to-use syntax and feature parity for all protocols
• Flexible and extensible, load your own transports and serializers
• Multiplexing, session stores and packet encryption
• Can be used between servers or in the browser
• Lower resource footprint and over better throughtput than plain sockets

How it works

Bytes transfered

Call buffering can reduce payload sizes at the cost of some initial latency. This makes a huge difference when you need to send a large number of small packets, such as multiplayer games do. See Nagle's algorithm.

Hardware pressure

Giving profiles to your traffic output creates a more predictable load on the system and on the network. Furthermore, instantiating less network calls reduces the resource required exponantially. This means that your application can now run on less expensive machines!

[Read more]

Install

    npm install kalm

Usage

Server

    const Kalm = require('kalm');

    // Listening for incoming UDP transactions on port 6000
    const server = Kalm.listen({
      port: 6000
    });

    server.on('connection', (client) => { 
      // Subscribe to 'user.action' channel
      client.subscribe('user.action', (req) => {
        /*
          req.body       The body of the request
          req.client     The connection handle reference
          req.frame      The details of the network frame
          req.session    The session store for that connection
        */
      });

      // Broadcast to all connections subscribed to the channel 'user.join'
      server.broadcast('user.join', { foo: 'bar' });
    });
    

Client

    import Kalm from 'kalm';

    // Opens a connection to the server
    // Port, transport and serial settings should match
    const client = Kalm.connect({
      hostname: '0.0.0.0', // Server's IP
      port: 6000 // Server's port
    });

    client.write('user.action', {body: 'This is an object!'}); 
    client.subscribe('user.join', () => { //... });

Options

Transports [wiki]

Name	Module
IPC	Kalm.transports.IPC
TCP	Kalm.transports.TCP
UDP	Kalm.transports.UDP
WebSockets	kalm-websocket

Serializers [wiki]

Name	Module
JSON	Kalm.serials.JSON
MSG-PACK	kalm-msgpack
Snappy	kalm-snappy
null	No transformation (data must be a Buffer or UInt8Array)

Profiles

Name	Module	Condition
dynamic	Kalm.profiles.dynamic	Triggers based on buffer size and maximum time range (default)
heartbeat	Kalm.profiles.heartbeat	Triggers at a fixed time interval
threshold	Kalm.profiles.threshold	Triggers when buffer reaches a certain size
realtime	Kalm.profiles.realtime	Triggers immediatly on writing to a queue
manual	Kalm.profiles.manual	Need to process queues by hand

Loading transports, profiles and serializers

    // Custom adapter loading example
    const Kalm = require('kalm');
    const ws = require('kalm-websocket');
    const msgpack = require('kalm-msgpack');

    const server = Kalm.listen({
      port: 3000,
      transport: ws,
      serial: msgpack,
      profile: { tick: 5, maxBytes: null } // Triggers every 5ms
    });

Encryption

You can optionaly enable payload encryption by simply putting a String/Number value to the secretKey property of both your client and server. The key has to be the same on both sides.

For better security, the key needs to be at least 16 characters long.

A null value (default), means no encryption.

Testing

Unit + Smoke tests

npm test

Benchmarks

node tests/benchmarks

Logging

Kalm uses debug

export DEBUG=kalm

Contribute

Please do! This is an open source project - if you see something that you want, open an issue or file a pull request.

If you have a major change, it would be better to open an issue first so that we can talk about it.

I am always looking for more maintainers, as well. Get involved.

License

Apache 2.0 (c) 2017 Frederic Charette