Server API | Socket.IO
Version: 3.x
Server API
Exposed by require("socket.io")
.
Related documentation pages:
httpServer
(http.Server) the server to bind to.options
(Object)
Works with and without new
:
const
io
=
require
(
"socket.io"
)
(
)
;
const
{
Server
}
=
require
(
"socket.io"
)
;
const
io
=
new
Server
(
)
;
Available options:
OptionDefault valueDescriptionpath
/socket.io
name of the path to captureserveClient
true
whether to serve the client filesadapter
-the adapter to use. Defaults to an instance of the Adapter
that ships with socket.io which is memory based. See socket.io-adapterparser
-the parser to use. Defaults to an instance of the Parser
that ships with socket.io. See socket.io-parser.connectTimeout
45000
the number of ms before closing a client that has not successfully joined a namespace.
Available options for the underlying Engine.IO server:
OptionDefault valueDescriptionpingTimeout
5000
how many ms without a pong packet to consider the connection closedpingInterval
25000
how many ms before sending a new ping packetupgradeTimeout
10000
how many ms before an uncompleted transport upgrade is cancelledmaxHttpBufferSize
1e6
how many bytes or characters a message can be, before closing the session (to avoid DoS).allowRequest
A function that receives a given handshake or upgrade request as its first parameter, and can decide whether to continue or not. The second argument is a function that needs to be called with the decided information: fn(err, success)
, where success
is a boolean value where false means that the request is rejected, and err is an error code.transports
["polling", "websocket"]
transports to allow connections toallowUpgrades
true
whether to allow transport upgradesperMessageDeflate
false
parameters of the WebSocket permessage-deflate extension (see ws module api docs). Set to true
to enable.httpCompression
true
parameters of the http compression for the polling transports (see zlib api docs). Set to false
to disable.wsEngine
ws
what WebSocket server implementation to use. Specified module must conform to the ws
interface (see ws module api docs). Default value is ws
. An alternative c++ addon is also available by installing the eiows module.cors
the list of options that will be forwarded to the cors modulecookie
the list of options that will be forwarded to the cookie moduleallowEIO3
false
whether to enable compatibility with Socket.IO v2 clients
More information here.
port
(Number) a port to listen to (a newhttp.Server
will be created)options
(Object)
See above for the list of available options
.
const
io
=
require
(
"socket.io"
)
(
3000
,
{
path
:
"/test"
,
serveClient
:
false
,
pingInterval
:
10000
,
pingTimeout
:
5000
,
cookie
:
false
}
)
;
options
(Object)
See above for the list of available options
.
const
io
=
require
(
"socket.io"
)
(
{
path
:
"/test"
,
serveClient
:
false
,
}
)
;
const
server
=
require
(
"http"
)
.
createServer
(
)
;
io
.
attach
(
server
,
{
pingInterval
:
10000
,
pingTimeout
:
5000
,
cookie
:
false
}
)
;
server
.
listen
(
3000
)
;
io
.
attach
(
3000
,
{
pingInterval
:
10000
,
pingTimeout
:
5000
,
cookie
:
false
}
)
;
- (Namespace)
An alias for the default (/
) namespace.
io
.
sockets
.
emit
(
"hi"
,
"everyone"
)
;
io
.
of
(
"/"
)
.
emit
(
"hi"
,
"everyone"
)
;
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.
const
io
=
require
(
"socket.io"
)
(
http
,
{
serveClient
:
false
}
)
;
const
io
=
require
(
"socket.io"
)
(
)
;
io
.
serveClient
(
false
)
;
io
.
attach
(
http
)
;
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"
)
;
const
socket
=
io
(
{
path
:
"/myownpath"
}
)
;
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
}
)
)
;
httpServer
(http.Server) the server to attach tooptions
(Object)
Attaches the Server
to an engine.io instance on httpServer
with the supplied options
(optionally).
port
(Number) the port to listen onoptions
(Object)
Attaches the Server
to an engine.io instance on a new http.Server with the supplied options
(optionally).
Synonym of server.attach(httpServer[, options]).
Synonym of server.attach(port[, options]).
engine
(engine.Server)- Returns
Server
Advanced use only. Binds the server to a specific engine.io Server
(or compatible API) instance.
socket
(engine.Socket)- Returns
Server
Advanced use only. Creates a new socket.io
client from the incoming engine.io (or compatible API) Socket
.
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
.
emit
(
"hello"
)
;
}
)
;
const
socket
=
io
(
"/dynamic-101"
)
;
dynamicNsp
.
emit
(
"hello"
)
;
dynamicNsp
.
use
(
(
socket
,
next
)
=>
{
}
)
;
With a function:
io
.
of
(
(
name
,
query
,
next
)
=>
{
next
(
null
,
checkToken
(
query
.
token
)
)
;
}
)
.
on
(
"connection"
,
(
socket
)
=>
{
}
)
;
callback
(Function)
Closes the Socket.IO server. The callback
argument is optional and will be called when all connections are closed.
Note: this also closes the underlying HTTP server.
const
Server
=
require
(
"socket.io"
)
;
const
PORT
=
3030
;
const
server
=
require
(
"http"
)
.
Server
(
)
;
const
io
=
Server
(
PORT
)
;
io
.
close
(
)
;
server
.
listen
(
PORT
)
;
io
=
Server
(
server
)
;
Overwrites the default method to generate your custom socket id.
The function is called with a node request object (http.IncomingMessage
) as first parameter.
const
uuid
=
require
(
"uuid"
)
;
io
.
engine
.
generateId
=
(
req
)
=>
{
return
uuid
.
v4
(
)
;
}
Represents a pool of sockets connected under a given scope identified by a pathname (eg: /chat
).
More information can be found here.
- (String)
The namespace identifier property.
- (Map<SocketId, Socket>)
A map of Socket instances that are connected to this namespace.
const
socketCount
=
io
.
of
(
"/admin"
)
.
sockets
.
size
;
- (Adapter)
The “Adapter” used for the namespace. Useful when using the Adapter
based on Redis, as it exposes methods to manage sockets and rooms across your cluster.
Note: the adapter of the main namespace can be accessed with io.of("/").adapter
.
Please see the explanation here.
room
(String)- Returns
Namespace
for chaining
Sets a modifier for a subsequent event emission that the event will only be broadcasted to clients that have joined the given room
.
To emit to multiple rooms, you can call to
several times.
const
io
=
require
(
"socket.io"
)
(
)
;
const
adminNamespace
=
io
.
of
(
"/admin"
)
;
adminNamespace
.
to
(
"level1"
)
.
emit
(
"an event"
,
{
some
:
"data"
}
)
;
Synonym of namespace.to(room).
eventName
(String)args
- Returns
true
Emits an event to all connected clients. The following two are equivalent:
const
io
=
require
(
"socket.io"
)
(
)
;
io
.
emit
(
"an event sent to all connected clients"
)
;
const
chat
=
io
.
of
(
"/chat"
)
;
chat
.
emit
(
"an event sent to all connected clients in chat namespace"
)
;
Note: acknowledgements are not supported when emitting from namespace.
- Returns
Promise<Set<SocketId>>
Gets a list of socket IDs connected to this namespace (across all nodes if applicable).
const
ids
=
await
io
.
allSockets
(
)
;
const
ids
=
await
io
.
in
(
"user:1234"
)
.
allSockets
(
)
;
const
ids
=
await
io
.
of
(
"/chat"
)
.
allSockets
(
)
;
const
ids
=
await
io
.
of
(
"/chat"
)
.
in
(
"general"
)
.
allSockets
(
)
;
fn
(Function)
Registers a middleware, which is a function that gets executed for every incoming Socket
, and receives as parameters the socket and a function to optionally defer execution to the next registered middleware.
Errors passed to middleware callbacks are sent as special connect_error
packets to clients.
io
.
use
(
(
socket
,
next
)
=>
{
const
err
=
new
Error
(
"not authorized"
)
;
err
.
data
=
{
content
:
"Please retry later"
}
;
next
(
err
)
;
}
)
;
socket
.
on
(
"connect_error"
,
err
=>
{
console
.
log
(
err
instanceof
Error
)
;
console
.
log
(
err
.
message
)
;
console
.
log
(
err
.
data
)
;
}
)
;
socket
(Socket) socket connection with client
Fired upon a connection from client.
io
.
on
(
"connection"
,
(
socket
)
=>
{
}
)
;
io
.
of
(
"/admin"
)
.
on
(
"connection"
,
(
socket
)
=>
{
}
)
;
Synonym of Event: “connection”.
Sets a modifier for a subsequent event emission that the event data may be lost if the clients are not ready to receive messages (because of network slowness or other issues, or because they’re connected through long polling and is in the middle of a request-response cycle).
io
.
volatile
.
emit
(
"an event"
,
{
some
:
"data"
}
)
;
Sets a modifier for a subsequent event emission that the event data will only be broadcast to the current node (when the Redis adapter is used).
io
.
local
.
emit
(
"an event"
,
{
some
:
"data"
}
)
;
A Socket
is the fundamental class for interacting with browser clients. A Socket
belongs to a certain Namespace
(by default /
) and uses an underlying Client
to communicate.
It should be noted the Socket
doesn’t relate directly to the actual underlying TCP/IP socket
and it is only the name of the class.
Within each Namespace
, you can also define arbitrary channels (called room
) that the Socket
can join and leave. That provides a convenient way to broadcast to a group of Socket
s (see Socket#to
below).
The Socket
class inherits from EventEmitter. The Socket
class overrides the emit
method, and does not modify any other EventEmitter
method. All methods documented here which also appear as EventEmitter
methods (apart from emit
) are implemented by EventEmitter
, and documentation for EventEmitter
applies.
More information can be found here.
- (String)
A unique identifier for the session, that comes from the underlying Client
.
- (Set)
A Set of strings identifying the rooms this client is in.
io
.
on
(
"connection"
,
(
socket
)
=>
{
console
.
log
(
socket
.
rooms
)
;
socket
.
join
(
"room1"
)
;
console
.
log
(
socket
.
rooms
)
;
}
)
;
- (Client)
A reference to the underlying Client
object.
- (engine.Socket)
A reference to the underlying Client
transport connection (engine.io Socket
object). This allows access to the IO transport layer, which still (mostly) abstracts the actual TCP/IP socket.
- (Request)
A getter proxy that returns the reference to the request
that originated the underlying engine.io Client
. Useful for accessing request headers such as Cookie
or User-Agent
.
const
cookie
=
require
(
"cookie"
)
;
io
.
on
(
"connection"
,
(
socket
)
=>
{
const
cookies
=
cookie
.
parse
(
socket
.
request
.
headers
.
cookie
||
""
)
;
}
)
;
- (Object)
The handshake details:
{
headers
:
,
time
:
,
address
:
,
xdomain
:
,
secure
:
,
issued
:
,
url
:
,
query
:
,
auth
:
}
Usage:
io
.
use
(
(
socket
,
next
)
=>
{
let
handshake
=
socket
.
handshake
;
}
)
;
io
.
on
(
"connection"
,
(
socket
)
=>
{
let
handshake
=
socket
.
handshake
;
}
)
;
HistoryVersionChangesv3.0.5Restoration of the first implementation.v3.0.0Removal in favor of socket.onAny()
.v1.7.2The error
event is sent directly to the client.v1.6.0First implementation.
fn
(Function)
Registers a middleware, which is a function that gets executed for every incoming Packet
and receives as parameter the packet and a function to optionally defer execution to the next registered middleware.
Errors passed to the middleware callback are then emitted as error
events on the server-side:
io
.
on
(
"connection"
,
(
socket
)
=>
{
socket
.
use
(
(
[
event
,
...
args
]
,
next
)
=>
{
if
(
isUnauthorized
(
event
)
)
{
return
next
(
new
Error
(
"unauthorized event"
)
)
;
}
next
(
)
;
}
)
;
socket
.
on
(
"error"
,
(
err
)
=>
{
if
(
err
&&
err
.
message
===
"unauthorized event"
)
{
socket
.
disconnect
(
)
;
}
}
)
;
}
)
;
args
ack
(Function)- Returns
Socket
Sends a message
event. See socket.emit(eventName[, …args][, ack]).
(overrides EventEmitter.emit
)
eventName
(String)args
ack
(Function)- Returns
true
Emits an event to the socket identified by the string name. Any other parameters can be included. All serializable data structures are supported, including Buffer
.
socket
.
emit
(
"hello"
,
"world"
)
;
socket
.
emit
(
"with-binary"
,
1
,
"2"
,
{
3
:
"4"
,
5
:
Buffer
.
from
(
[
6
]
)
}
)
;
The ack
argument is optional and will be called with the client’s answer.
io
.
on
(
"connection"
,
(
socket
)
=>
{
socket
.
emit
(
"an event"
,
{
some
:
"data"
}
)
;
socket
.
emit
(
"ferret"
,
"tobi"
,
(
data
)
=>
{
console
.
log
(
data
)
;
}
)
;
}
)
;
(inherited from EventEmitter
)
eventName
(String)callback
(Function)- Returns
Socket
Register a new handler for the given event.
socket
.
on
(
"news"
,
(
data
)
=>
{
console
.
log
(
data
)
;
}
)
;
socket
.
on
(
"news"
,
(
arg1
,
arg2
,
arg3
)
=>
{
}
)
;
socket
.
on
(
"news"
,
(
data
,
callback
)
=>
{
callback
(
0
)
;
}
)
;
Inherited from EventEmitter
(along with other methods not mentioned here). See the Node.js documentation for the events module.
callback
(Function)
Register a new catch-all listener.
socket
.
onAny
(
(
event
,
...
args
)
=>
{
console
.
log
(
`
got
${
event
}
`
)
;
}
)
;
callback
(Function)
Register a new catch-all listener. The listener is added to the beginning of the listeners array.
socket
.
prependAny
(
(
event
,
...
args
)
=>
{
console
.
log
(
`
got
${
event
}
`
)
;
}
)
;
listener
(Function)
Removes the previously registered listener. If no listener is provided, all catch-all listeners are removed.
const
myListener
=
(
)
=>
{
}
;
socket
.
onAny
(
myListener
)
;
socket
.
offAny
(
myListener
)
;
socket
.
offAny
(
)
;
- Returns
Function[]
Returns the list of registered catch-all listeners.
const
listeners
=
socket
.
listenersAny
(
)
;
room
(string) | (string[])- Returns
void
|Promise
Adds the socket to the given room
or to the list of rooms.
io
.
on
(
"connection"
,
(
socket
)
=>
{
socket
.
join
(
"room 237"
)
;
console
.
log
(
socket
.
rooms
)
;
socket
.
join
(
[
"room 237"
,
"room 238"
]
)
;
io
.
to
(
"room 237"
)
.
emit
(
"a new user has joined the room"
)
;
}
)
;
The mechanics of joining rooms are handled by the Adapter
that has been configured (see Server#adapter
above), defaulting to socket.io-adapter.
For your convenience, each socket automatically joins a room identified by its id (see Socket#id
). This makes it easy to broadcast messages to other sockets:
io
.
on
(
"connection"
,
(
socket
)
=>
{
socket
.
on
(
"say to someone"
,
(
id
,
msg
)
=>
{
socket
.
to
(
id
)
.
emit
(
"my message"
,
msg
)
;
}
)
;
}
)
;
room
(String)- Returns
void
|Promise
Removes the socket from the given room
.
io
.
on
(
"connection"
,
(
socket
)
=>
{
socket
.
leave
(
"room 237"
)
;
io
.
to
(
"room 237"
)
.
emit
(
`
user
${
socket
.
id
}
has left the room
`
)
;
}
)
;
Rooms are left automatically upon disconnection.
room
(String)- Returns
Socket
for chaining
Sets a modifier for a subsequent event emission that the event will only be broadcasted to clients that have joined the given room
(the socket itself being excluded).
To emit to multiple rooms, you can call to
several times.
io
.
on
(
"connection"
,
(
socket
)
=>
{
socket
.
to
(
"others"
)
.
emit
(
"an event"
,
{
some
:
"data"
}
)
;
socket
.
to
(
"room1"
)
.
to
(
"room2"
)
.
emit
(
"hello"
)
;
socket
.
to
(
)
.
emit
(
"hey"
)
;
}
)
;
Note: acknowledgements are not supported when broadcasting.
Synonym of socket.to(room).
value
(Boolean) whether to following packet will be compressed- Returns
Socket
for chaining
Sets a modifier for a subsequent event emission that the event data will only be compressed if the value is true
. Defaults to true
when you don’t call the method.
io
.
on
(
"connection"
,
(
socket
)
=>
{
socket
.
compress
(
false
)
.
emit
(
"uncompressed"
,
"that's rough"
)
;
}
)
;
close
(Boolean) whether to close the underlying connection- Returns
Socket
Disconnects this socket. If value of close is true
, closes the underlying connection. Otherwise, it just disconnects the namespace.
io
.
on
(
"connection"
,
(
socket
)
=>
{
setTimeout
(
(
)
=>
socket
.
disconnect
(
true
)
,
5000
)
;
}
)
;
Sets a modifier for a subsequent event emission that the event data will only be broadcast to every sockets but the sender.
io
.
on
(
"connection"
,
(
socket
)
=>
{
socket
.
broadcast
.
emit
(
"an event"
,
{
some
:
"data"
}
)
;
}
)
;
Sets a modifier for a subsequent event emission that the event data may be lost if the client is not ready to receive messages (because of network slowness or other issues, or because they’re connected through long polling and is in the middle of a request-response cycle).
io
.
on
(
"connection"
,
(
socket
)
=>
{
socket
.
volatile
.
emit
(
"an event"
,
{
some
:
"data"
}
)
;
}
)
;
reason
(String) the reason of the disconnection (either client or server-side)
Fired upon disconnection.
io
.
on
(
"connection"
,
(
socket
)
=>
{
socket
.
on
(
"disconnect"
,
(
reason
)
=>
{
}
)
;
}
)
;
Possible reasons:
ReasonDescriptionserver namespace disconnect
The socket was forcefully disconnected with socket.disconnect()client namespace disconnect
The client has manually disconnected the socket using socket.disconnect()server shutting down
The server is, well, shutting downping timeout
The client did not send a PONG packet in the pingTimeout
delaytransport close
The connection was closed (example: the user has lost connection, or the network was changed from WiFi to 4G)transport error
The connection has encountered an error
reason
(String) the reason of the disconnection (either client or server-side)
Fired when the client is going to be disconnected (but hasn’t left its rooms
yet).
io
.
on
(
"connection"
,
(
socket
)
=>
{
socket
.
on
(
"disconnecting"
,
(
reason
)
=>
{
console
.
log
(
socket
.
rooms
)
;
}
)
;
}
)
;
Note: those events, along with connect
, connect_error
, newListener
and removeListener
, are special events that shouldn’t be used in your application:
socket
.
emit
(
"disconnect"
)
;
The Client
class represents an incoming transport (engine.io) connection. A Client
can be associated with many multiplexed Socket
s that belong to different Namespace
s.
- (engine.Socket)
A reference to the underlying engine.io
Socket
connection.
- (Request)
A getter proxy that returns the reference to the request
that originated the engine.io connection. Useful for accessing request headers such as Cookie
or User-Agent
.