Socketbox
Socketbox is real time socket layer framework inspired by express.You can simulate socket messages like as restful request, build router system according to a specific protocol and write middleware to this routers.
import Socketbox from 'socketbox';
// First create your own socket server.
const ws = new WebSocket.Server( { port : 8080 } );
// you give socket server instance to socketbox
const app = new Socketbox();
app.createServer( ws );
//you create router
const router = Socketbox.Router();
//you activate router on this websocket server.
app.use( '/', router );Installation
This is a Node.js module available through the npm registry.
Before installing, download and install Node.js. Node.js 7 or higher is required.
$ npm install socketboxSupported socket types
- Websocket
Socketbox opts
const app = new Socketbox(opts);| Events | Description |
|---|---|
ping |
(boolean) ping-pong activate, server send ping message automatic |
pingTimeout |
(number) seconds, ping sending timeout |
Basic text message based ping-pong
Your client listen ping text message and reply to this message
!! Strongly recommend set clientTracking to false in websocket opts
// client connect to server
var wsClient = new WebSocket('ws://localhost:8080', opts);
// example Web browser websocket
wsClient.onmessage = function(message){
if(message.data === 'ping') {
wsClient.send('pong');
}
}If your client dont reply ping message, server know client is down and clear client data on system.
Socketbox client events
app.on(<events>, (client) => {
console.log(`${client.ip} is connected`);
});| Events | Description |
|---|---|
connected |
Emitted client connected |
disconnected |
Emitted client disconnected |
Event callback give one parameter, it is client object.
Client sessions
Your each client have own session object.You can edit session add and remove directly. You can write data to client session.
// example:
// you validate client and returned user object.You
// can put user to client session.You can access session in each request
// session everytime stored until client disconnect
router.register( '/validate/token', ( req, res ) => {
req.session.user = validate(req.body.token); //use session.user on each request
} );Socket message protocol (Client message format)
You need to adjust some rules while send message to this socket server from client. Your socket message architecture below;
{
url: 'ws://omer.com/message/write', // hostname and protocol is required current version
body: {
to: 'x',
from: 'y',
message: 'hi!'
}
}| Property | Description |
|---|---|
url |
( required ) your defined url on backend server |
body |
( optional ) if you want put data to your message |
you can put query your url.
{
url: 'ws://omer.com/message/get?messageId=11993'
}Router
router.register( '/message/write', ( req, res ) => {
res.send( { statusCode : 200 } );
} );you can use params while register route path.
router.register( '/message/write/:userid', ( req, res ) => {
/**
* Access to params
* req.params.userid
*
* If you have query in request;
* req.query.[<your query name>]
*/
res.send( { statusCode : 200 } );
} );Middleware
You can add property to request object on middleware.
const mid1 = ( req, res, next ) => {
req.user = {};
req.user.username = 'dmomer';
next();
};
router.register( '/profile', mid1, ( req, res ) => {
res.send( req.user );
} );Cache
You can access socketbox cache but recommend only use the following methods. Cache class is static class and read-only.Clients is stored in a Map object.
// return everytime same cache class.
const cache = Socketbox.Cache();Method: cache.clients()
- Returns: All clients in a Array.
don't take parameters.
Method: cache.filter(key)
- key
<string> | <Function>You will be passed to key string or direct working filter function. - Returns: All clients in a Array.
Following is two differenct parameter example:
// we have map , which is [['1', {name: 'omer'}], ['2', {name: 'demircan'}]]
// use string key
cache.filter('1'); // return only values [{name: 'omer'}]
// use own filter function;
// following function filter objects, which contains name key is 'omer'
cache.filter((item) => {
// item[1] is value.
return item[1].name === 'demircan'
}) // return [{name: 'demircan'}];Channels
You can bind clients to channels.You can send message to channel if you want.
Join to channel
Method: join( cname )
- cname
<String>channel name for join
// if channel is not exist, method create channel.
client.join('channel1');
// ex:
// you can listen join router
router.register('/join?room=223', (req, res) => {
res.join(req.query.room);
});Send message to channel
Method: sendTo(message, cname)
- message
<String>message content - cname
<String>channel name to go
res.sendTo({message: x}, 'channel1');Leave from channel
Request
You can use some request properties.
req.body; //you can access message body
// if url is /a/b?keyword=omer
// you can access req.query.keyword (value is omer)
req.query; //this is object
// if url is /a/b/:name
// you can access req.params.name (value is any)
req.params; //this is object
// if your url is wss://omer.com/p/a/t/h?query=string#hash
req.protocol; //wss:
req.host; //omer.com
req.hostname; //omer.com
req.port; // null
req.path; // /p/a/t/h?query=string
req.pathname // /p/a/t/h
req.href; // wss://omer.com/p/a/t/h?query=string#hash
req.query; // 'query=string'
req.hash; // #hashResponse
Actually response object is client reference.
You can put string, json or buffer to message.
// you can send Object or raw string
res.send({name: 'omer'});
res.send(new Buffer('omer'));Leave from room
Method: leave( cname )
- cname
<String>channel name for leave
If client is leaved, return true otherwise return false.
// res is client reference on all request, you can access to client object using res.
res.leave('room1');