Server

Exposed by require('socket.io').

new Server(httpServer[, options])

• httpServer (http.Server) the server to bind to.
• options (Object)

Works with and without new:

const io = require(‘socket.io’)();
// or
const Server = require(‘socket.io’);
const io = new Server();

Available options:

Available options for the underlying Engine.IO server:

Among those options:

• The pingTimeout and pingInterval parameters will impact the delay before a client knows the server is not available anymore. For example, if the underlying TCP connection is not closed properly due to a network issue, a client may have to wait up to pingTimeout + pingInterval ms before getting a disconnect event.

• The order of the transports array is important. By default, a long-polling connection is established first, and then upgraded to WebSocket if possible. Using ['websocket'] means there will be no fallback if a WebSocket connection cannot be opened.

const server = require(‘http’).createServer();

const io = require(‘socket.io’)(server, {
  path: ‘/test’,
  serveClient: false,
  // below are engine.IO options
  pingInterval: 10000,
  pingTimeout: 5000,
  cookie: false
});

server.listen(3000);

new Server(port[, options])

• port (Number) a port to listen to (a new http.Server will be created)
• options (Object)

See above for the list of available options.

const io = require(‘socket.io’)(3000, {
  path: ‘/test’,
  serveClient: false,
  // below are engine.IO options
  pingInterval: 10000,
  pingTimeout: 5000,
  cookie: false
});

new Server(options)

• options (Object)

See above for the list of available options.

const io = require(‘socket.io’)({
  path: ‘/test’,
  serveClient: false,
});

// either
const server = require(‘http’).createServer();

io.attach(server, {
  pingInterval: 10000,
  pingTimeout: 5000,
  cookie: false
});

server.listen(3000);

// or
io.attach(3000, {
  pingInterval: 10000,
  pingTimeout: 5000,
  cookie: false
});

server.sockets

• (Namespace)

An alias for the default (/) namespace.

io.sockets.emit(‘hi’, ‘everyone’);
// is equivalent to
io.of(‘/‘).emit(‘hi’, ‘everyone’);

server.serveClient([value])

• value (Boolean)
• Returns Server|Boolean

If value is true the attached server (see Server#attach) will serve the client files. Defaults to true. This method has no effect after attach is called. If no arguments are supplied this method returns the current value.

// pass a server and the serveClient option
const io = require(‘socket.io’)(http, { serveClient: false });

// or pass no server and then you can call the method
const io = require(‘socket.io’)();
io.serveClient(false);
io.attach(http);

server.path([value])

• value (String)
• Returns Server|String

Sets the path value under which engine.io and the static files will be served. Defaults to /socket.io. If no arguments are supplied this method returns the current value.

const io = require(‘socket.io’)();
io.path(‘/myownpath’);

// client-side
const socket = io({
  path: ‘/myownpath’
});

server.adapter([value])

• value (Adapter)
• Returns Server|Adapter

Sets the adapter value. Defaults to an instance of the Adapter that ships with socket.io which is memory based. See socket.io-adapter. If no arguments are supplied this method returns the current value.

const io = require(‘socket.io’)(3000);
const redis = require(‘socket.io-redis’);
io.adapter(redis({ host: ‘localhost’, port: 6379 }));

server.origins([value])

• value (String|String[])
• Returns Server|String

Sets the allowed origins value. Defaults to any origins being allowed. If no arguments are supplied this method returns the current value.

io.origins([‘https://foo.example.com:443‘]);

server.origins(fn)

• fn (Function)
• Returns Server

Provides a function taking two arguments origin:String and callback(error, success), where success is a boolean value indicating whether origin is allowed or not. If success is set to false, error must be provided as a string value that will be appended to the server response, e.g. “Origin not allowed”.

Potential drawbacks:

• in some situations, when it is not possible to determine origin it may have value of *
• As this function will be executed for every request, it is advised to make this function work as fast as possible
• If socket.io is used together with Express, the CORS headers will be affected only for socket.io requests. For Express you can use cors.

io.origins((origin, callback) => {
  if (origin !== ‘https://foo.example.com‘) {
    return callback(‘origin not allowed’, false);
  }
  callback(null, true);
});

server.attach(httpServer[, options])

• httpServer (http.Server) the server to attach to
• options (Object)

Attaches the Server to an engine.io instance on httpServer with the supplied options (optionally).

server.attach(port[, options])

• port (Number) the port to listen on
• options (Object)

Attaches the Server to an engine.io instance on a new http.Server with the supplied options (optionally).

server.listen(httpServer[, options])

Synonym of server.attach(httpServer[, options]).

server.listen(port[, options])

Synonym of server.attach(port[, options]).

server.bind(engine)

• engine (engine.Server)
• Returns Server

Advanced use only. Binds the server to a specific engine.io Server (or compatible API) instance.

server.onconnection(socket)

• socket (engine.Socket)
• Returns Server

Advanced use only. Creates a new socket.io client from the incoming engine.io (or compatible API) Socket.

server.of(nsp)

• nsp (String|RegExp|Function)
• Returns Namespace

Initializes and retrieves the given Namespace by its pathname identifier nsp. If the namespace was already initialized it returns it immediately.

const adminNamespace = io.of(‘/admin’);

A regex or a function can also be provided, in order to create namespace in a dynamic way:

const dynamicNsp = io.of(/^\/dynamic-\d+$/).on(‘connection’, (socket) => {
  const newNamespace = socket.nsp; // newNamespace.name === ‘/dynamic-101’

  // broadcast to all clients in the given sub-namespace
  newNamespace.emit(‘hello’);
});

// client-side
const socket = io(‘/dynamic-101’);

// broadcast to all clients in each sub-namespace
dynamicNsp.emit(‘hello’);

// use a middleware for each sub-namespace
dynamicNsp.use((socket, next) => { / … / });

With a function:

io.of((name, query, next) => {
  // the checkToken method must return a boolean, indicating whether the client is able to connect or not.
  next(null, checkToken(query.token));
}).on(‘connection’, (socket) => { / … / });

server.close([callback])

• callback (Function)

Closes the socket.io server. The callback argument is optional and will be called when all connections are closed.

const Server = require(‘socket.io’);
const PORT   = 3030;
const server = require(‘http’).Server();

const io = Server(PORT);

io.close(); // Close current server

server.listen(PORT); // PORT is free to use

io = Server(server);

server.engine.generateId

Overwrites the default method to generate your custom socket id.

The function is called with a node request object (http.IncomingMessage) as first parameter.

io.engine.generateId = (req) => {
  return “custom:id:” + custom_id++; // custom id must be unique
}