SockJS support for Node.js

Introduction

SockJS is a browser/server communication framework designed to provide a WebSocket-like programming model when native WebSocket support is unavailable or unreliable.

This extension supports the server side and the client side of the following SockJS libraries:

Objects

Metamodel name Description
CAST_NodeJS_WebSocket_Server Represents a WebSocket server endpoint identified by its path
CAST_NodeJS_WebSocket_Client Represents a WebSocket client entrypoint identified by its path

A NodeJS WebSocket Server object is created as soon as the server is instantiated (sockjs.createServer(...)), even if no handler is ever registered on it and it never sends any data. A server is named {} when its path cannot be statically determined (for example when the path is passed as a runtime parameter). A server named {} is treated as a catch-all endpoint.

A NodeJS WebSocket Client object is created as soon as the client is instantiated (new SockJS(...)), even if no handler is ever registered on it and it never sends any data. A client is named {} when its path cannot be statically determined (for example when the path is passed as a runtime parameter).

Link type From To Created when
callLink NodeJS WebSocket Server NodeJS Function / Method A handler is registered on the server (on('connection', ...), on('data', ...), on('close', ...), on('end', ...), on('error', ...))
callLink NodeJS Function / Method NodeJS WebSocket Server A function sends a message to clients (broadcast) or calls .send() from outside a registered handler — see filtering rule below
callLink NodeJS WebSocket Client NodeJS Function / Method A handler is registered on the server (onopen, onmessage, onclose, onerror)
callLink NodeJS Function / Method NodeJS WebSocket Client A function iniatiates a connection to a server

Supported API methods

sockjs package

API method Object created / linked Link type
sockjs.createServer(options) NodeJS WebSocket Server —
server.on(event, handler), also once and addEventListener fn linked as callee of server callLink
conn.write(...) / conn.send(...) called from a registered handler Calling function → NodeJS WebSocket Server —

sockjs-client package or the browser global SockJS

API method Object created / linked Link type
new SockJS(url, ...) NodeJS WebSocket Client —
sock.onopen = handler fn linked as callee of client callLink
sock.onmessage = handler fn linked as callee of client callLink
sock.onclose = handler fn linked as callee of client callLink
sock.onerror = handler fn linked as callee of client callLink
sock.send(...) / sock.write(...) Calling function → NodeJS WebSocket Client —

Example

sockjs and sockjs-client

const http = require('http');
const path = require('path');
const express = require('express');
const sockjs = require('sockjs');

const app = express();
app.use(express.static(path.join(__dirname, 'public')));

const clients = new Set();

const sjs = sockjs.createServer({
  prefix: '/socket',
  websocket: true,
  heartbeat_delay: 10000,   // short, so you can actually watch 'h' frames arrive
  disconnect_delay: 5000,
  log: (sev, msg) => { if (sev !== 'debug') console.log(`[sockjs:${sev}] ${msg}`); },
});

const SockJS = require('sockjs-client');
const WebSocket = require('ws');

const BASE = 'http://localhost:3000/socket';

function viaSockJS() {
  return new Promise((resolve) => {
    console.log('\n=== A. sockjs-client ===');
    const sock = new SockJS(BASE, null, { transports: ['websocket'] });

    sock.onopen = () => {
      console.log(`open  transport=${sock.transport}`);
      console.log(`url   ${sock.url}`);
      sock.send(JSON.stringify({ type: 'echo', text: 'from sockjs-client' }));
      setTimeout(() => sock.close(), 800);
    };
    sock.onmessage = (e) => console.log('msg  ', e.data);
    sock.onclose = (e) => { console.log(`close code=${e.code}`); resolve(); };
  });
}

This produces:

  • one NodeJS WebSocket Server object named /socket
  • one NodeJS WebSocket Client object named http://localhost:3000/socket
  • a callLink from NodeJS WebSocket Client to onopen
  • a callLink from NodeJS WebSocket Client to onmessage
  • a callLink from NodeJS WebSocket Client to onclose

Assuming that the websocket client connects to the websocket server, you will get the following result: