Middleware Functions

JavaScript | TypeScript

Page Content:

• Verify Connecting User
• Verify Subscribing User
• On Unsubscribe
• On Channel Open and Close
• Listen to all Publish events on the Server
• Communicate between Workers and Machines
• Pre-process message on receive

Examples are available in ClusterWS-Examples repository.

Here you can find all middlewares which are supported in ClusterWS. setMiddleware function should be called outside of wss.on('connection', (socket) => {}), example:

// setMiddleware code
wss.setMiddleware('middleware name', () => {})

// listen on connection to websocket server
wss.on('connection', (socket) => {})

Verify Connecting User

If you want to verify the user which is trying to connect to the WebSocket Server you can use verifyConnection middleware function.

wss.setMiddleware('verifyConnection', (info, next) => {
     // stop user from connecting to WebSocket Server
     next(false) // wss.on('connection') won't be called

     // or you can proceed it by passing true in callback
     next(true)

     // you can use variable info to find different values and compare.
     // Example origin:
     console.log(info.origin) // ex: https://localhost
})

Verify Subscribing User

You can verify user which is trying to subscribe to the channels by using onSubscribe middleware function:

wss.setMiddleware('onSubscribe', (socket, channel, next) => {
      // You can do validation in here

      // will not subscribe user to the channel
      next(false) 

      // will subscribe user to the channel
      next(true) 
})

On Unsubscribe

Event is fired when socket is unsubscribed from the some channel

Note this event is only called when clients send unsubscribe event (it will not be called on unexpected close).

wss.setMiddleware('onUnsubscribe', (socket, channel) => {
 // socket: client which has unsubscribed from the channel
 // channel: name of the channel
})

On Channel Open and Close

You can perform some actions at the time when first user (in that particular worker) subscribe to the channel (open new channel) or when the last user (in that particular worker) unsubscribe from the channel (destroy channel).

wss.setMiddleware('onChannelOpen', (channel) => {
 // channel: name of the channel
})

wss.setMiddleware('onChannelClose', (channel) => {
 // channel: name of the channel
})

Listen to all Publish events

You can use onPublish middleware function to catch all messages which are published to the channels (only if this channel exist on this particular server, worker)

wss.setMiddleware('onPublish', (channel, data) => { 
    // channel: name of the channel
    // data: data which is published to the channel
})

Communicate between Workers and Machines

You can communicate across all workers (including on the other machines) through the private communication channel:

// Listen on messages from workers
wss.setMiddleware('onMessageFromWorker', (data) => {
    // execute any code on message form workers
})

// Send message to all workers including current one
// you can call this method from everywhere in your code
wss.publishToWorkers('Any message you want to send')

Pre-process message on receive

This function allows you to pre-process messages when they loaded to the server but not passed to the socket itself

Note Important you must execute next() and pass message which is parsed to process farther or null if you don't want that massage to propagate.

wss.setMiddleware('onMessageReceive', (socket, message, next) => {
 // socket: client which sent message
 // message: in pure format (if useBinary set to true it will be binary)
 // next: callback function to return ready message

   next(null) // will not pass message
   next(JSON.parse(message)) // will pass message down to socket
})