Abstracted WebSocket module with event driven interface and rich functionalities. See also evsocket-client. Server side uses ws module to implement WebSocket server. See full example here.
There is well-known alternative for this module, Socket.io, but unfortunately Socket.io doesn't support React Native, because it uses Node.js features inside. This module built for provide highly abstracted WebSocket interface without any Node.js related features, only used pure JavaScript features. When I was used WebSocket with vanila JS, it was really hard to make something rich. EvSocket provides similar interface like Socket.io with only uses WebSocket + JavaScript features so it is safe to use any WebSocket supporting JavaScript platform.
- Event Driven Interface
- Easy Authentication
- Binary Transmission
- Middlewares
- Channel system(like Room in Socket.io)
- Socket Broadcasting
- And more...!
Event Driven is super useful interface that implement complicated web applications easily. Plain WebSocket only supports onmessage and send() method to exchange data, but most of time, you want to send and get data with multiple entries. For this, EvSocket supports Event Driven interface like Socket.io(as you can see the name, EvSocket means EventSocket), and if you already used Socket.io, this will really easy to use.
// Server Side
const http = require('http');
const httpServ = http.createServer();
const evsocket = require('evsocket');
const server = evsocket.createServer({ server: httpServ });
server.on('connection', (socket) => {
console.log('Socket connected.');
});
//Client Side
var socket = new EvSocket("ws://localhost:3000");
socket.on('open', () => {
socket.send('boom', 'BOOM!');
});You can set any event name you want, and you can trigger any event whenever you want. Also it supports object sending/getting, if you sent object, it will automatically do serializing/parsing jobs when receiver got the message, so you don't have to serialize or parse JavaScript object everytime.
WebSocket supports sending ArrayBuffer, that is built-in native binary data format. However there is no way to send binary data with string at once. This makes hard to implement Event Driven interface with binary transmission. EvSocket supports Event Driven binary transmission, inside, it converts some metadata like event name to binary data and combine them together. And then EvSocket send the bundled binary data, and when got this, detach the metadata from this, and parse the metadata to find correct event name of binary transffering destination. Want to know more about this, please check string-binary-attacher module that I made for this purpose.
For provide better performance, to send binary data via EvSocket, you should use sendBinary() instead of send().
// Server Side
socket.once('send-binary', (bin) => {
console.log('Got binary from client: ', bin);
socket.sendBinary('got-binary', bin); // send back
});
// Client Side
socket.once('got-binary', function(bin) {
console.log('Got binary from server: ' + new Uint8Array(bin).toString());
});
var uint8Array = new Uint8Array([0,1,2,3,4,5,6,7]);
socket.sendBinary('send-binary', uint8Array);Also it supports sending Node.js Buffer. Internally it converts to ArrayBuffer.
EvSocket automatically generate unique id for each socket when it's connected.
// Server Side
server.on('connection', (socket) => {
console.log('Connected: ' + socket.id);
});
// Client Side
var socket = new EvSocket("ws://localhost:3000");
socket.on('open', () => {
console.log('ID is ' + socket.id);
});EvSocket provides Middleware system. Each message from client passing through these middlewares and you can access the data between middlewares and modify it. This system inspired from connect and express's middleware system.
const evsocket = require('evsocket');
// Set Middlewares
evsocket.setMiddleware((socket, data, next) => {
console.log('Middleware 1', data);
next();
});
evsocket.setMiddleware((socket, data, next) => {
// console.log('Middleware 2 (Async)', recv);
// setTimeout(next, 1000);
console.log('Middleware 2', data);
next();
});
evsocket.setMiddleware((socket, data, next) => {
console.log('Middleware 3', data);
// next();
// Give Error here
next(new Error('Stop!'));
});
evsocket.setMiddleware((socket, data, next) => {
console.log('Middleware 4', data);
next();
});
evsocket.setErrorMiddleware((error, socket, data, next) => {
console.log('Error Middleware 1', error);
next();
});
evsocket.setErrorMiddleware((error, socket, data, next) => {
console.log('Error Middleware 2', error);
next();
});EvSocket provides built-in authenticating system, which useful to authenticate socket. Only you have to do is use useAuth() method to generate own authentication rule and apply it when client socket created. Then server and client exchange their data and authenticate it by your own rule. After it succeeds, it calling 'authenticated' events both, else, it calling 'unauthorized' events both and close the socket automatically after event fires.
// Server Side
evsocket.useAuth((socket, data, done) => {
if(data.id === '.modernator' && data.password === '1234') {
done();
}
else {
done(new Error('Unauthorized.'));
}
});
//Client Side
var socket = new EvSocket('ws://localhost:3000', {
auth: {
id: '.modernator',
password: '1234'
}
});
socket.on('open', function() {
console.log('Connected as ' + socket.id);
socket.on('authenticated', () => {
console.log('Authenticated.');
// your code goes here...
});
socket.on('unauthorized', (err) => {
console.log('unauthorized.');
});
});Channel system allows you to grouping sockets easily. Also you can broadcast message to other sockets in same channel.
socket.on('chat', (msg) => {
console.log(msg);
});
socket.join('channel1');
socket.broadcast('chat', 'Hello!');evSocket.broadcast() sends message to all users in the same channel. This is quite useful to implement chat room like something.
Possible options follows this doc.
const evsocket = require('evsocket');
const server = evsocket.createServer({ port: 3000});
server.on('connection', (socket) => { ... });Add a middleware. Callback function receives 3 arguments, socket, recv, next. socket argument is EvSocket and recv is object that has event name with data.
const EvSocket = require('evsocket');
EvSocket.setMiddleware((socket, data, next) => {
recv.data = base64_encoding(data);
next();
});Add an error middleware. Callback function receives 4 arguments, error, socket, recv, next. error is Error Object that contains error information.
const EvSocket = require('evsocket');
EvSocket.setMiddleware((socket, data, next) => {
if(!socket.someRequiredData) {
return next(new Error('Unauthorized'));
}
next();
});
EvSocket.setErrorMiddleware((error, socket, data, next) => {
socket.send('error', error);
socket.close();
});Add authentication function. Callback function receives 3 arguments, socket, data, done. Data is just data received from client.
const EvSocket = require('evsocket');
const secretKey = 'some-secret';
EvSocket.useAuth((socket, data, done) => {
if(data.secretKey !== secretKey) {
return done(new Error('Invalid key.'));
}
done();
});// Client
var EvSocket = new EvSocket('ws://localhost:3000', {
auth: { key: 'some-secret' }
});When new Socket is connected, connection event will emit and send EvSocket instance as first argument.
Close WebSocket.
server.on('connection', (socket) => {
socket.close();
});Send the data with event name to client.
server.on('connection', (socket) => {
socket.send('client-ev', 'hello, client!');
});Send the binary data with event name to client.
server.on('connection', (socket) => {
socket.sendBinary('some-client-event', new Uint8Array([1,2,3,4,5,6,7,8]));
});Add event listener.
Add event listener that execute only once and delete itself automatically.
Remove event listener. If fn argument is undefined, remove all listeners in specified event name.
Fires event of server socket.
Join the specified channel.
server.on('connection', (socket) => {
socket.on('channeljoin', (channelName) => {
console.log(`Channel ${channelName} joined.`);
});
socket.join('channel1');
});Leave the current channel.
socket.join('channel1');
console.log(socket.channelName); // channel1
socket.leave();
console.log(socket.channelName); // EmptyBroadcast message to users who currently in same channel.
server.on('connection', (socket) => {
socket.on('channeljoin', (channelName) => {
console.log(`Channel ${channelName} joined.`);
socket.broadcast('chat', `${socket.id} joined in ${channelName}.`);
});
socket.join('channel1');
});Broadcast message to users who in specified channel.
socket.broadcastTo('some-channel', 'chat', 'helloworld!');Multicast message to users who matches filter.
// Multicast only that has someProp property in socket.
socket.multicast(function(sock) {
return sock.someProp === true;
};You can use any name of the event, except these default events. These default events are triggering by EvSocket directly.
Fired on socket closed. Arguments are code and reason, please check this: https://developer.mozilla.org/en-US/docs/Web/API/CloseEvent#Status_codes
Fired on error occured. Has one argument, error object.
Fired on EvSocket passed authentication.
Fired on EvSocket failed authentication. After this event occurs, socket will close.
Fired on user joined channel.
Fired on user left channel.