README
socket.io-router-middleware
Easy to use router for sockets with methods (categories) for better code organization. Only works with Socket.io v2 because it relies on socket.use() method.
This library uses (route-parser)[https://www.npmjs.com/package/route-parser] for parsing the route paths. For info about how to write your paths please take a look at their docs.
Install
npm install --save socket.io-router-middleware
Usage
Example usage with Express server
Server
const app = require('express')()
const http = require('http').Server(app);
const io = require('socket.io')(http);
const port = process.env.PORT || 3000;
// Require the router
const IORouter = new require('socket.io-router-middleware');
// Instantiate the router
const iorouter = new IORouter();
// Add router paths
iorouter.on('/api/:param?sort=:sort', (socket, ctx, next) => {
ctx.response = {hello: 'from server'}
socket.emit('response', ctx);
// Don't forget to call next() at the end to enable passing to other middlewares
next();
});
// On client connection attach the router
io.on('connection', function (socket) {
socket.use((packet, next) => {
// Call router.attach() with the client socket as the first parameter
iorouter.attach(socket, packet, next)
});
});
http.listen(port, function(){
console.log('listening on *:' + port);
});
In the callback function of the route you have to send and event back and also call next()
to let the flow continue to other middlewares.
The name of the event is up to you but you have to listen for it on the frontend to actually get something back from the server.
I usually use response
as the event name. Also you dont need to send the response event with the ctx
object but anything you want BUT the ctx
object
contains useful information like the original request object and matching route. The structure of the ctx
object by default is as follows:
const ctx = {
request: {
method: 'on',
params: {
...routeParams
},
route: '/matching/route?paramName=paramValue',
...anyOtherDataYouSend
},
response: {} // empty response object
}
You can fill the response object with the data in the callback function like this: ctx.response = {hello: 'world'}
. And you can also add other properties.
I usually stick to single response object for all the data but you can send whatever you want like errors for example. If there is an error you want to send though
I would go with invoking it by executing the next
funtion with an error instance like next(new Error('error content'))
. Which will let the socket.io client
handle the error rather than you having to handle it yourself.
Client
<script src="https://cdnjs.cloudflare.com/ajax/libs/socket.io/2.3.0/socket.io.js"></script>
<script>
// connect to socket server
const socket = io();
// emit an event to your route path
socket.emit('/api/test?sort=asc', {
// payload is not required but can be used to send data
payload: {
hello: 'from client'
}
});
// listen for response from server
socket.on('response', ({request, response}) => {
...
});
</script>
You can send anything you want in the socket.emit payload and it will be available to the server but some keys in the object are reserved:
method
: Should be used to call a specific method set inallowedMethods
parameter on the server. (If using theon
method it can be left blank)params
: Is filled by the router and contains parameters defined in the route configroute
: Contains the currently matched route
Parameters
allowedMethods
Specify methods (categories) of the router. This serves as an organizing tool only. It doesn't have any other effect.
The default method that is ALWAYS generated is on
. Specifying any routes here will create shorthand methods for calling them. For example
const router = new Router(['get', 'post']);
router.post('/api/create', (socket, ctx, next) => {...})
router.get('/api/read', (socket, ctx, next) => {...})
router.on('/api/update', (socket, ctx, next) => {...})
If left blank only the on
shorthand will be generated
Methods
.attach(socket, packet, next)
Attches a router to the socket.
io.on('connection', function (socket) {
socket.use((packet, next) => {
router.attach(socket, packet, next)
});
});
.route(method, route, callbackFn)
Universal function that is used by shorthand methods created with allowedMethods
.
!!! This function does not create the methods (categories) so passing a method that has not been defined in allowedMethods
will result in an error
router.route('on', '/api/send', (socket, ctx, next) => {...})
.on(route, callbackFn)
A shorthand for router.route('on', '/route/path', (socket, ctx, next) => {})
aka the default route that is always available