Please update documentation to show how to reject a ... | socketio/socket.io

Is your feature request related to a problem? Please describe.
I spent about an hour messing around to figure this out, but I needed a way to drop (or reject) a packet from a middleware, without erroring out (next(error)). This is for an ACL I'm working on to only allow users to emit on a channel if they have permission.
I have found a solution, and feel it should be included in the documentation for future reference.

Describe the solution you'd like
I would like, probably in the socket middleware section, to show a way to drop packets from a middleware (I have found a way, but any way really).

I did it by simply returning from the middleware:

io.use(function(socket,next) {
    socket.use(function([event,data],next) {
        if(true /* some condition for dropping the packet */) return
        else next()
    })
    next()
})

Describe alternatives you've considered
I've only really tried the above solution I found (other than about an hour of googling and eating the docs)

Additional context
As in my context, this functionality is very useful for user/access control, and allowed me to consolidate a good amount of code into this one middleware. This functionality is also already present, but not mentioned in the documentation and examples, and I believe this functionality could prove very popular if the documentation could mention it and have the idea in developers minds

Also, here is a fully functional example (using express and socket.io) demonstrating dropping every other packet based on a incrementing id:


const app = require('express')()

const http = require('http').Server(app)

const io = require('socket.io')(http)

io.use(function(socket,next) {
	console.log("io middleware hit")
	socket.use(function([event,data],next) {
		console.log("socket middleware hit")
		if(data.ttl % 2) {
			console.log("dropping packet: ",data.ttl)
			return
		} else {
			console.log("passing packet: ",data.ttl)
			next()
		}
	})
	next()
})
io.on("connection",function(socket) {
	socket.on("ping",function(data,ack) {
		console.log("server got client ping: ",data.ttl)
		ack(data)
		socket.emit("pong",data,function(res) {
			console.log("client acknowledged pong: ",res.ttl)
		})
	})
})
io.on("ping",function(data,ack) {
	console.log("server broadcast got ping: ",data.ttl)
	ack(data)
	socket.emit("pong",data)
})

app.get("/",(req,res) => {
	res.send(`
<!DOCTYPE html>
<html>
    <head>
        <title>Test</title>
    </head>
    <body>
        <script src="/socket.io/socket.io.js"></script>
        <script>
            var socket = io();
            var pid = 0
            var int
            //console.log("awaiting socket connection")
            socket.on('connect',function() {
                console.log("socket connected")
                int = setInterval(function() {
                    let _pid = pid++
                    console.log("client pinging server: ",_pid)
                    socket.emit("ping",{ttl: _pid},function(res) {
                        console.log("Server acknowledged ping: ",res.ttl)
                    })
                },1000)
            })
            socket.on('disconnect',function() {
                console.log("socket disconnected")
                clearInterval(int)
            })
            socket.on('pong',function(data,ack) {
                console.log("client got pong: ",data.ttl)
                ack(data)
            })
        </script>
    </body>
</html>
		`)
})

http.listen(8000,() => {
	console.log("listening on http://localhost:8000/")
})

Running this example shows that all packets where ttl is odd are dropped, and no ack function is called and no error is emitted.

I have not gone much into depth on this though (I got the functionality I needed), but I'm sure adding it to the documentation and having other devs look at it will uncover more features and edge cases.

Thank you for considering my request!

Please update documentation to show how to reject a packet from socket middleware

Description

Contributor guide

First steps

Research direction

Assessment