easy-websocket-server v1.0.0
easy-websocket-server
An easy-to-use wrapper around the ws api for an express-like feel.
npm i easy-websocket-server
Examples
const app = require('express')();
const server = require('http').createServer(app);
const easySocket = require('easy-websocket-server');
const { send, broadcastAll } = easySocket.commands;
const socket = easySocket(server);
// Listen for connections
socket.onConnection(id => console.log(`${id} just connected!`))
// Listen for someMethod messages
socket.onMessage(`someMethod`, (id, message) => {
console.log(`${id} sent a message:`, message);
});
// Listen for otherMethod messages
socket.onMessage(`otherMethod`, (id, message) => {
console.log(`${id} sent a message:`, message);
})
// Send a message to a particular client
send(`someId`, `someMethod`, { ok: true });
// Broadcast to all the clients
broadcastAll(`someMethod`, { ok: true });
server.listen(3000);
Using without express is exactly the same, except you just call:
const server = require('http').createServer();
Instead of this:
const server = require('http').createServer(app);
Remotes
Using the built in remoteEngine (similar to using express.Router()
);
// index.js
const app = require('express')();
const server = require('http').createServer(app);
const socket = require('easy-websocket-server')(server);
const createUser = require('./remotes/create-user');
socket.useRemote(`createUser`, createUser);
server.listen(3000);
// ./remotes/create-user.js
const remote = require('easy-websocket-server').remoteEngine();
remote.onMessage(id => {
// ...
console.log(`User created!`);
})
module.exports = remote;
There is a more thorough example in the /test
directory.
Sending messages from the client
All must messages from the client are recomended to have this format:
{
"method": "someMethod",
"data": "Whatever you wish to send. Can be a string, object, or array."
}
If a client sends up a message without a method
property, you can assign to the message a default
method.
socket.use((id, message, next) => {
if (!message.method) message.method = `default`;
next();
})
Then you can handle the message like this:
socket.onMessage(`default`, (id, message) => {
// Do something...
})
API
const easySocket = require('easy-socket-server');
easySocket(server)
const socket = easySocket(server);
The server
should be a http/https server instance.
socket.onServerUpgrade(callback: (next, quit, request, socket, head) => void)
The callback
is called every time when the server upgrades a http(s) request to a websocket.
To keep the request from executing further, call quit()
, otherwise you can call next()
.
Example:
socket.onServerUpgrade((next, quit, request, socket, head) => {
if (someCondition) next();
else quit();
})
socket.onConnection(callback: id => void)
The callback
is called everytime a new websocket connection is recieved. If quit
or next
are not called in socket.onServerUpgrade
, then this will happen right after onServerUpgrade
.
The id
is the random id assigned to the client.
socket.use(callback: (id, message, next) => void)
Custom middleware, just like express.use()
socket.onMessage(method: String, callback: (id, message) => void)
The callback
is called everytime a message is recieved whose method property equals method
.
socket.onClose(callback: (id, code) => void)
The callback
is called whenever a websocket connection closes. id
will be the id of the connection that closed.
socket.useRemote(method: String, remote: remoteEngine)
The remote
is the remoteEngine to use for the given method
.
Now easySocket will call the onMessage
method on the remote when the message's method property equals method
.
Here is an example.
socket.catchErrors(callback: (error, id, message) => void)
The callback
is called every time an unhandled error or promise rejection occurs in the message processing pipeline. message
and id
are the message that was being processed when the error occured, and the id of the client that sent that message.
easySocket.commands
const { commands } = easySocket;
commands.send(id, method, data)
The id
is the id of the client to send the message to.
The method
is the method of the message.
The data
is what is to me sent in the message.
commands.broadcastAll(method, data)
Same as commands.send
, except that it broadcasts a message to all the clients.
commands.broadcastExclude()]
The id
is the id of the client to exclude.
Otherwise, id is the same as commands.broadcastAll
.
commands.close(id?)
If and id
is given, easySocket will close only that connection, otherwise, it will close all the connections.
commands.getConnections(): Object
Returns an object of all the connections. Here is an sample of what that might look like:
{
"socketId1568846090925": {
"id": "socketId1568846090925",
"incommingMessages": [
{
"method": "default",
"data": "this is fake"
}
],
"outgoingMessages": [
{
"method": "someMethod",
"data": "so is this"
}
],
"ip": "::1"
}
}
easySocket.remoteEngine()
const remote = require('easy-websocket-server').remoteEngine();
// Do something...
module.exports = remote;
See this example.
remote.onMessage(callback: (id, message) => void)
The callback
will be called when a message is recieved with a method that matches the method
paramater in the socket.useRemote
function.
easySocket.hasConnected(id?): Boolean
Checks if a connection exists.
The id
is the id of the connection to check. If no id is given, easySocket will check for at least one connection.
Thanks
Many thanks to @websockets/ws, the backbone of this package.
License
5 years ago
5 years ago