Socket.IO Middleware: Your Connection Gatekeeper

Why it exists

Socket.IO middleware exists to run logic on a connection before it is fully established. This provides a crucial checkpoint for security and control, allowing you to inspect, validate, or reject incoming connections before they can access your main application logic and start emitting events.

The mental model

Think of middleware as a bouncer at a nightclub. The bouncer (middleware) checks every person (incoming connection) at the door. They might check an ID (auth token), see if you're on a list (validation), or turn you away if the club is full (rate limiting). Only after the bouncer says "go" by calling next() can you enter the club and join the party (triggering the connection event). If they say "no" by calling next(new Error()), you're denied entry.

How it works

You register middleware functions on the server using io.use((socket, next) => { ... }). This function receives the socket object for the pending connection and a next callback. Inside, you can access connection details, including credentials sent from the client via the auth option, which are available in socket.handshake.auth. To allow the connection, you call next(). To reject it, you call next(new Error('reason')). If rejected, the client receives a connect_error event. You can register multiple middleware functions; they run sequentially until one passes an error or the chain completes.

When to use it

Use middleware for tasks that must happen once, at the very beginning of a connection's lifecycle. The three primary use cases are: first, authentication, by validating a token passed from the client; second, authorization, by checking if the authenticated user has permission to connect; and third, rate limiting or logging connection attempts.

When not to use it

Do not use middleware for logic that runs on every message; that's what event handlers like socket.on('my_event', ...) are for. It is also distinct from Express middleware. While io.engine.use() allows some compatibility, Socket.IO middleware is for the WebSocket connection lifecycle, not the HTTP request/response cycle. Finally, because the socket is not fully connected, you cannot emit events to it or rely on the disconnect event firing from within the middleware.

One canonical example

A common use case is token-based authentication. The client sends a token, and the server middleware verifies it before allowing the connection.

Client-side:

const socket = io({ auth: { token: "your_jwt_here" } });

Server-side:

`io.use((socket, next) => {
const token = socket.handshake.auth.token;
if (myAuthService.isValid(token)) {
next();
} else {
next(new Error("Authentication error"));
}
});`

If the token is invalid, the connection is refused, and the client's connect_error listener will fire with the error message.