socket.io-protocol
This repository contains the protocol specification and JavaScript
parser for the Socket.IO protocol.
Protocol version
Current protocol revision: 1
.
Parser API
Parser#encode(Object:packet):String
Encodes a Packet
object as a string.
Parser#decode(String:packet):Packet
Returns a Packet
object for the given string. If a parsing error
occurs the returned packet is an error object.
Parser#types
Array of packet type keys.
Packet
Each packet is represented as a vanilla Object
with a nsp
key that
indicates what namespace it belongs to (see "Multiplexing") and a
type
key that can be one of the following:
Packet#CONNECT
(0
)Packet#DISCONNECT
(1
)Packet#EVENT
(2
)Packet#ACK
(3
)Packet#ERROR
(4
)
EVENT
-
data
(Array
) a list of arguments, the first of which is the event
name. Arguments can contain any type of field that can result of
JSON
decoding, including objects and arrays of arbitrary size.
-
id
(Number
) if the id
identifier is present, it indicates that the
server wishes to be acknowledged of the reception of this event.
ACK
data
(Array
) see EVENT
data
.id
(Number
) see EVENT
id
.
ERROR
Transport
The socket.io protocol can be delivered over a variety of transports.
socket.io-client
is the implementation of the protocol for the browser and Node.JS over
engine.io-client.
socket.io is the server
implementation of the protocol over
engine.io.
Multiplexing
Socket.IO has built-in multiplexing support, which means that each packet
always belongs to a given namespace
, identified by a path string (like
/this
). The corresponding key in the Packet
object is nsp
.
When the socket.io transport connection is established, a connection
attempt to the /
namespace is assumed (ie: the server behaves as if
the client had sent a CONNECT
packet to the /
namespace).
In order to support multiplexing of multiple sockets under
the same transport, additional CONNECT
packets can be sent by the
client to arbitrary namespace URIs (eg: /another
).
When the server responds with a CONNECT
packet to the corresponding
namespace, the multiplexed socket is considered connected.
Alternatively, the server can respond with an ERROR
packet to indicate
a multiplexed socket connection error, such as authentication errors.
The associated error payload varies according to each error, and can
be user-defined.
After a CONNECT
packet is received by the server for a given nsp
,
the client can then send and receive EVENT
packets. If any of the
parties receives an EVENT
packet with an id
field, an ACK
packet is
expected to confirm the reception of said packet.
License
MIT