The present document describes the protocol and encoding a client/server pair must follow to establish a successful Socket.IO connection.
The present document describes the latest version of the protocol, 1.
Versions are a single integer incremented with each revision of the protocol.
Socket.IO aims to bring a WebSocket-like API to many browsers and devices, with some specific features to help with the creation of real-world realtime applications and games.
- Multiple transport support (old user agents, mobile browsers, etc).
- Multiple sockets under the same connection (namespaces).
- Disconnection detection through heartbeats.
- Optional acknoledgments.
- Reconnection support with buffering (ideal for mobile devices or bad networks)
- Lightweight protocol that sits on top of HTTP.
Anatomy of a Socket.IO socket
A Socket.IO client first decides on a transport to utilize to connect.
The state of the Socket.IO socket can be
The transport connection can be
A simple HTTP handshake takes place at the beginning of a Socket.IO connection. The handshake, if successful, results in the client receiving:
- A session id that will be given for the transport to open connections.
- A number of seconds within which a heartbeat is expected (
- A number of seconds after the transport connection is closed when the socket
is considered disconnected if the transport connection is not reopened (
At this point the socket is considered connected, and the transport is signaled to open the connection.
If the transport connection is closed, both ends are to buffer messages and then frame them appropriately for them to be sent as a batch when the connection resumes.
If the connection is not resumed within the negotiated timeout the socket is considered disconnected. At this point the client might decide to reconnect the socket, which implies a new handshake.
Socket.IO HTTP requests
Socket.IO HTTP URIs take the form of:
[scheme] '://' [host] '/' [namespace] '/' [protocol version] '/' [transport id] '/' [session id] '/' ( '?' [query] )
Only the methods
POST are utilized (for the sake of compatibility
with old user agents), and their usage varies according to each transport.
The main transport connection is always a
The URI scheme is decided based on whether the client requires a secure connection
or not. Defaults to
https is the recommended one.
The host where the Socket.IO server is located. In the browser environment, it
defaults to the host that runs the page where the client is loaded (
The connecting client has to provide the namespace where the Socket.IO requests are intercepted.
This defaults to
socket.io for all client and server distributions.
Each client should ship with the revision ID it supports, available as a public interface to developers.
For example, the browser client supports
The following transports are supported:
The client first figures out what transport to use. Usually this occurs in the browser, utilizing feature detection.
User-defined transports are allowed.
The query component (eg:
?token=48737481747&) is not present on all URLs.
Certain query keys are reserved by Socket.IO:
t: Contains a timestamp, only used to bypass caching on certain old UAs.
disconnect: Triggers a disconnection.
User-defined query components are allowed. For example,
?t=1238141910&token=mytoken is a valid query).
The client will perform an initial HTTP POST request like the following
The absence of the
transport id and
session id segments will signal the server
this is a new, non-handshaken connection.
The server can respond in three different ways:
- 401 Unauthorized
If the server refuses to authorize the client to connect, based on the supplied
Cookie header or custom query components).
No response body is required.
- 503 Service Unavailable
If the server refuses the connection for any reason (eg: overload).
No response body is required.
- 200 OK
The handshake was successful.
The body of the response should contain the session id (
sid) given to the
client, followed by the heartbeat timeout, the connection closing timeout,
and the list of supported transports separated by
The absence of a heartbeat timeout ('') is interpreted as the server and client not expecting heartbeats.
Once the handshake request-response cycle is complete (and it ended with success),
a new connection is opened by the transport that was negotiated, with a
The transport can modify the URI if the transport requires it, as long as no
information is lost. For example, if
websocket is accepted as the transport,
and the connection was secure, the URI for the transport connection will become:
The URI still contains all the information required by Socket.IO to continue the message exchange (protocol security, namespace, protocol version, transport, etc).
Messages can be sent and received by following this convention. How the messages are encoded and framed depends on each transport, but generally boils down to whether the transport has built-in framing (unidiretionally and/or bidirectionally).
Transports that initialize unidirectional connections (where the server can
write to the client but not vice-versa), should perform
POST requests to send
data back to the server to the same endpoint URI.
Certain transports, like
flashsocket, have built-in lightweight
framing mechanisms for sending and receiving messages.
xhr-multipart, the built-in MIME framing is used for the sake of consistency.
When no built-in lightweight framing is available, and multiple messages need to be delivered (i.e: buffered messages), the following is used:
`\ufffd` [message lenth] `\ufffd`
Transports where the framing overhead is expensive (ie: when the xhr-polling transport tries to send data to the server).
Messages have to be encoded before they're sent. The structure of a message is as follows:
[message type] ':' [message id ('+')] ':' [message endpoint] (':' [message data])
The message type is a single digit integer.
The message id is an incremental integer, required for ACKs (can be ommitted).
If the message id is followed by a
+, the ACK is not handled by socket.io,
but by the user instead.
Socket.IO has built-in support for multiple channels of communication (which we call "multiple sockets"). Each socket is identified by an endpoint (can be omitted).
Signals disconnection. If no endpoint is specified, disconnects the entire socket.
Disconnect a socket connected to the
Disconnect the whole socket
Only used for multiple sockets. Signals a connection to the endpoint. Once the server receives it, it's echoed back to the client.
Example, if the client is trying to connect to the endpoint /test, a message like this will be delivered:
'1::' [path] [query]
To acknowledge the connection, the server echoes back the message. Otherwise, the server might want to respond with a error packet.
Sends a heartbeat. Heartbeats must be sent within the interval negotiated with the server. It's up to the client to decide the padding (for example, if the heartbeat timeout negotiated with the server is 20s, the client might want to send a heartbeat evert 15s).
'3:' [message id ('+')] ':' [message endpoint] ':' [data]
A regular message.
4) JSON Message
'4:' [message id ('+')] ':' [message endpoint] ':' [json]
A JSON encoded message.
'5:' [message id ('+')] ':' [message endpoint] ':' [json encoded event]
An event is like a json message, but has mandatory
name is a string and
args an array.
The event names
'message' 'connect' 'disconnect' 'open' 'close' 'error' 'retry' 'reconnect'
are reserved, and cannot be used by clients or servers with this message type.
'6:::' [message id] '+' [data]
An acknowledgment contains the message id as the message data. If a
follows the message id, it's treated as an event message packet.
Example 1: simple acknowledgement
Example 2: complex acknowledgement
'7::' [endpoint] ':' [reason] '+' [advice]
For example, if a connection to a sub-socket is unauthorized.
No operation. Used for example to close a poll after the polling duration times out.
Forced socket disconnection
A Socket.IO server must provide an endpoint to force the disconnection of the socket.
While closing the transport connection is enough to trigger a disconnection, it sometimes is desirable to make sure no timeouts are activated and the disconnection events fire immediately.
The server must respond with
200 OK, or
500 if a problem is detected.