Skip to main content

How to use with express-session

There are two ways to share the session context between Express and Socket.IO, depending on your use case:

1st use case: Socket.IO only retrieves the session context​

This is useful when the authentication is handled by Express (or Passport) for example.

In that case, we can directly use the session middleware:

import express from "express";
import { createServer } from "http";
import { Server } from "socket.io";
import session from "express-session";

const app = express();
const httpServer = createServer(app);

const sessionMiddleware = session({
secret: "changeit",
resave: false,
saveUninitialized: false
});

app.use(sessionMiddleware);

app.post("/login", (req, res) => {
req.session.authenticated = true;
res.status(204).end();
});

const io = new Server(httpServer);

// convert a connect middleware to a Socket.IO middleware
const wrap = middleware => (socket, next) => middleware(socket.request, {}, next);

io.use(wrap(sessionMiddleware));

// only allow authenticated users
io.use((socket, next) => {
const session = socket.request.session;
if (session && session.authenticated) {
next();
} else {
next(new Error("unauthorized"));
}
});

io.on("connection", (socket) => {
console.log(socket.request.session);
});

Please check the example with Passport here.

2nd use case: Socket.IO can also create the session context​

This is useful if you want to use express-session without an Express application for example.

In that case, we need to customize the headers sent during the handshake:

import { createServer } from "http";
import { Server } from "socket.io";
import session from "express-session";

const httpServer = createServer();

const sessionMiddleware = session({
secret: "changeit",
resave: false,
saveUninitialized: false
});

const io = new Server(httpServer, {
allowRequest: (req, callback) => {
// with HTTP long-polling, we have access to the HTTP response here, but this is not
// the case with WebSocket, so we provide a dummy response object
const fakeRes = {
getHeader() {
return [];
},
setHeader(key, values) {
req.cookieHolder = values[0];
},
writeHead() {},
};
sessionMiddleware(req, fakeRes, () => {
if (req.session) {
// trigger the setHeader() above
fakeRes.writeHead();
// manually save the session (normally triggered by res.end())
req.session.save();
}
callback(null, true);
});
},
});

io.engine.on("initial_headers", (headers, req) => {
if (req.cookieHolder) {
headers["set-cookie"] = req.cookieHolder;
delete req.cookieHolder;
}
});

io.on("connection", (socket) => {
console.log(socket.request.session);
});

Please check the example here.

Modifying the session​

Since it is not bound to an HTTP request, the session must be manually reloaded and saved:

io.on("connection", (socket) => {
const req = socket.request;

socket.on("my event", () => {
req.session.reload((err) => {
if (err) {
return socket.disconnect();
}
req.session.count++;
req.session.save();
});
});
});

You can also use a middleware which will be triggered for each incoming packet:

io.on("connection", (socket) => {
const req = socket.request;

socket.use((__, next) => {
req.session.reload((err) => {
if (err) {
socket.disconnect();
} else {
next();
}
});
});

// and then simply
socket.on("my event", () => {
req.session.count++;
req.session.save();
});
});
caution

Calling req.session.reload() updates the req.session object:

io.on("connection", (socket) => {
const session = socket.request.session;

socket.use((__, next) => {
session.reload(() => {
// WARNING! "session" still points towards the previous session object
});
});
});

Handling logout​

You can use the session ID to make the link between Express and Socket.IO:

io.on("connection", (socket) => {
const sessionId = socket.request.session.id;

socket.join(sessionId);
});

app.post("/logout", (req, res) => {
const sessionId = req.session.id;

req.session.destroy(() => {
// disconnect all Socket.IO connections linked to this session ID
io.to(sessionId).disconnectSockets();
res.status(204).end();
});
});

Handling session expiration​

const SESSION_RELOAD_INTERVAL = 30 * 1000;

io.on("connection", (socket) => {
const timer = setInterval(() => {
socket.request.session.reload((err) => {
if (err) {
// forces the client to reconnect
socket.conn.close();
// you can also use socket.disconnect(), but in that case the client
// will not try to reconnect
}
});
}, SESSION_RELOAD_INTERVAL);

socket.on("disconnect", () => {
clearInterval(timer);
});
});

With TypeScript​

To add proper typings to the session details, you will need to extend the IncomingMessage object from the Node.js "http" module.

Which gives, in the first case:

import { Request, Response, NextFunction } from "express";
import { Session } from "express-session";

declare module "http" {
interface IncomingMessage {
session: Session & {
authenticated: boolean
}
}
}

io.use((socket, next) => {
sessionMiddleware(socket.request as Request, {} as Response, next as NextFunction);
});

And in the second case:

import { Request, Response } from "express";
import { Session } from "express-session";
import { IncomingMessage } from "http";

declare module "http" {
interface IncomingMessage {
cookieHolder?: string,
session: Session & {
count: number
}
}
}

const io = new Server(httpServer, {
allowRequest: (req, callback) => {
// with HTTP long-polling, we have access to the HTTP response here, but this is not
// the case with WebSocket, so we provide a dummy response object
const fakeRes = {
getHeader() {
return [];
},
setHeader(key: string, values: string[]) {
req.cookieHolder = values[0];
},
writeHead() {},
};
sessionMiddleware(req as Request, fakeRes as unknown as Response, () => {
if (req.session) {
// trigger the setHeader() above
fakeRes.writeHead();
// manually save the session (normally triggered by res.end())
req.session.save();
}
callback(null, true);
});
},
});

io.engine.on("initial_headers", (headers: { [key: string]: string }, req: IncomingMessage) => {
if (req.cookieHolder) {
headers["set-cookie"] = req.cookieHolder;
delete req.cookieHolder;
}
});

Reference: TypeScript's Declaration Merging