How to wire up socket.io to a completely custom routing implementation.

[Arlen22]

I have a custom server implementation with bespoke routing. How can I route requests into socket.io once I'm done with all the pre-calculations? The documentation has examples for binding to ten+ different servers but it doesn't say how to just route requests into it manually. Obviously the fallback to long polling would have to be handled differently.

[Andrew1326]

Socket.IO doesn't expose a "route this request into me" API directly, but you can wire it up to a raw Node.js http.Server (or even a standalone engine) and manually forward requests. Here are two approaches:

1. Attach to a raw http.Server and handle routing yourself

Create an http.Server with your custom routing, and let Socket.IO handle only its own paths:

import { createServer } from 'http';
import { Server } from 'socket.io';

const httpServer = createServer((req, res) => {
  // Your custom routing logic runs first
  if (req.url?.startsWith('/my-custom-route')) {
    // Handle your routes
    res.writeHead(200);
    res.end('OK');
    return;
  }

  // Everything else falls through to Socket.IO's
  // built-in HTTP handler (long-polling transport)
  // Socket.IO will ignore paths it doesn't recognize
});

const io = new Server(httpServer, {
  path: '/socket.io/', // Socket.IO only handles this path
});

io.on('connection', (socket) => {
  console.log('connected:', socket.id);
});

httpServer.listen(3000);

Socket.IO intercepts the upgrade event (for WebSocket) and HTTP requests to its path automatically. Your custom routing handles everything else.

2. Use the standalone Engine.IO for full control

If you need to manually decide when to hand off a request to Socket.IO (e.g., after auth checks, rate limiting, etc.), use the lower-level engine.io directly:

import { createServer } from 'http';
import { Server } from 'socket.io';

const httpServer = createServer();
const io = new Server(); // Don't attach to httpServer yet

// Manually attach — this gives you the engine instance
io.attach(httpServer, {
  path: '/socket.io/',
});

// Or for even more control, intercept upgrade manually:
httpServer.on('upgrade', (req, socket, head) => {
  // Your pre-calculations / auth / routing
  const isSocketIO = req.url?.startsWith('/socket.io/');

  if (isSocketIO) {
    // Let Socket.IO handle the WebSocket upgrade
    // (this happens automatically when attached, shown for clarity)
  } else {
    // Handle other WebSocket connections or reject
    socket.destroy();
  }
});

httpServer.listen(3000);

3. Middleware approach (recommended for pre-processing)

If your goal is to run custom logic before Socket.IO processes the connection, use Socket.IO's middleware instead of routing:

const io = new Server(httpServer);

// Runs before every connection is established
io.use((socket, next) => {
  // Access the original HTTP request
  const req = socket.request;

  // Your pre-calculations here
  const token = req.headers.authorization;
  const customHeader = req.headers['x-custom-route'];

  // Attach data to the socket for later use
  socket.data.userId = verifyToken(token);
  socket.data.route = customHeader;

  next(); // or next(new Error('unauthorized'))
});

io.on('connection', (socket) => {
  // socket.data has your pre-calculated values
  console.log('User:', socket.data.userId);
});

TL;DR: Socket.IO is designed to own its path (/socket.io/) on an http.Server. You don't route into it — you attach it to a server and let it intercept its own path. For pre-processing, use io.use() middleware. For coexisting with custom routes, share the same http.Server and let each handle its own paths.

[Arlen22]

The middleware does get me most of the way there with socket.request, but I have multiple HTTP listeners in one process and I need all of them connecting to the same socket.io. To make things more complicated, different listeners could be mounted on "folders" (URL path prefixes) which means that I have to set a separate path for each io.attach call. This allows multiple reverse proxy configs to route to different ports.

After exploring the source code, I determined that I could seamlessly call io.attach for each http server. The only place this matters is when io.close is called and I'm never calling that, since I can just call close on each http server directly.

What I ended up doing was prepending a request listener to each http server after calling io.attach (so it gets called before engine.io) and recording the path prefix for that server in the request, which I can then retrieve in the middleware.