The socket manager
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
src
tests
.gitignore
.npmignore
.travis.yml
CODE_OF_CONDUCT.md
CONTRIBUTING.md
LICENSE
README.md
index.js
package-lock.json
package.json
yarn.lock

README.md

Kalm

Kalm

The Socket Manager



Kalm Node Build Status Dependencies Status Gitter


  • 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
          req.reply      Replys to the other client on the same channel
        */
      });

      // 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