rbmp v3.3.0

rbmp

Reactive Binary Messaging Protocol

Library to facilitate binary messaging over WebSocket connection for reactive applications. It may be used for lean browser-to-server, server-to-browser, and server-to-server communication. Library allows for unidirectional/bidirectional streams, request/response or publish/subscribe messaging patterns.

Send a request thru WebSocketConnector, and compose a response in WebSocketController message handler. Subscribe for a topic with WebSocketConnector in the client app, and enable subscription in WebSocketController in the server app to stream messages over the WebSocket.

Both WebSocketConnector and WebSocketController can be instantiated in NodeJS or browser. In most cases, WebSocketConnector is used in NodeJS or browser client app, while WebSocketController is used in NodeJS server app. But it is also possible to have the roles reversed for more exotic communication scenarios. For example, browser app can establish connections to multiple NodeJS server apps, and then add those connections to WebSocketController to publish updates to those NodeJS apps that subscribe for it.

Target: ES2020 browser or NodeJS.

ByteArray

ByteArray is a byte buffer view designed for compact data representation and minimal transmission footprint. It supports big-endian serialization/deserialization of multitude of different data types, primitive and complex. Specify binary types as JSON object for most compact serialization of object, or let it pack using default type mapping.

ByteArrayMessage

ByteArrayMessage is a ByteArray with topic string header to enable filtering and various messaging patterns, such as request/response and publish/subscribe.

WebSocketConnector

WebSocketConnector implements self-repairing WebSocket connection. If connection fails, WebSocketConnector attempts to reconnect. Upon reconnection, all subscriptions are restored. WebSocketConnector can be used to:

• call message handlers for incoming binary data;
• send binary data over WebSocket connection;
• post message as a request to await on the first response;
• subscribe/unsubscribe connection to/from messages of publishing server.

WebSocketController

WebSocketController is request/response and publish/subscribe facilitator. Add newly established WebSocket connections to WebSocketController to enable server functionality. WebSocketController can be used to:

• call message handlers for incoming binary data;
• send binary data over WebSocket connection;
• subscribe/unsubscribe connection to/from given topic;
• publish binary message to WebSockets subscribed for specific topic.

Creating connection in browser app

Sample code to create connection in browser app:

const prot = location.protocol.includes( 'https' ) ? 'wss' : 'ws';
const host = window.location.hostname;
const conn = new WebSocketConnector( () =>
	new WebSocket( `${ prot }://${ host }` )
);

Creating connection in NodeJS app

Sample code to create connection in nodejs app:

import * as WebSocket from 'ws';
...
const addr = `wss://127.0.0.1`;
const conn = new WebSocketConnector( () =>
	new WebSocket( addr, { rejectUnauthorized: false } )
);

Encoding complex object

Sample code to encode data using JSON type definition:

const msg = new ByteArrayMessage( 'Custom Topic' );
msg.write( complexObj, {
	uint32Prop: 'uint32',
	strProp: 'str',
	optionalInt64Prop: [ '?', 'int64' ],
	arr: [ 'array', 'int16' ],
	obj: {
		bufProp: 'buf',
		saveTime: 'datetime'
	},
	map: [ 'map', 'uint64', 'str' ]
} );

Streaming binary data

Sample code to stream binary data:

// stream buffers
conn.on( 'message', data => {
	console.log( `Buffer received: ${ data.byteLength }` );
} );
...
// stream messages
conn.emit( msg => {
	console.log( `Message received: ${ msg.topic }` );
} );

Implementing request/response

Sample code to request some server data:

// client app: send a request message and await to receive response message
const conn = new WebSocketConnector( () => new WebSocket( 'ws://localhost:8000' ) );
await conn.once( 'connected' );
const req = new ByteArrayMessage( 'Topic 101010' );
req.writeInt32( 101011 );
req.writeString( 'text' );
req.writeNullable( true, req.writeBoolean );
req.writeArray( [ 123, 456 ], req.writeUint32 );
const res = await conn.post( req );
console.log( `Received response ${ res.topic }` );
...
// server app: create WebSocket server and controller to reply
const controller = new WebSocketController();
const wss = new WebSocket.Server( { port: port } );
controller.emit( ( ws, msg ) => {
	console.log( 'received request' );
	const val = msg.readInt32();
	const res = new ByteArrayMessage( msg.topic );
	res.writeInt32( -val );
	controller.send( ws, res );
} );
wss.on( 'connection', ( ws, req  ) => {
	controller.add( ws, req.socket.remoteAddress );
} );

Implementing server managed publish/subscribe

Sample code to subscribe to some server message streams:

// client app: subscribe to the topic 'SomeTopic'
conn.subscribe( 'SomeTopic', msg => {
	console.log( `Message ${ msg.topic }` );
} );
...
// client app: subscribe to messages on topic 'MyTopic' for 5 seconds
const abortController = new AbortController();
conn.subscribe( 'MyTopic', msg => {
	console.log( `Subscription message ${ msg.topic }` );
}, abortController.signal );
setTimeout( () => {
	abortController.abort();
}, 5000 );
...
// server app: create WebSocket server and controller to reply
const controller = new WebSocketController();
controller.emit( ( ws, msg ) => {
	console.log( 'received subscription' );
	controller.subscribe( ws, msg );
} );
const wss = new WebSocket.Server( { port: port } );
wss.on( 'connection', ( ws, req  ) => {
	controller.add( ws, req.socket.remoteAddress );
} );
setTimeout( () => {
	const publication = new ByteArrayMessage( 'MyTopic' );
	publication.writeBigInt( 123n );
	publication.writeString( 'Test' );
	wsc.publish( publication );
}, 10000 );