This document describes the Socket.IO protocol. For a reference JavaScript implementation, take a look atsocket.io-parser,socket.io-clientandsocket.io.
Current protocol revision:4.
An object that encodes socket.io packets to engine.io-transportable form. Its only public method is Encoder#encode.
Encoder#encode(Object:packet, Function:callback)
Encodes aPacketobject into an array of engine.io-compatible encodings. If the object is pure JSON the array will contain a single item, a socket.io encoded string. If the object contains binary data (ArrayBuffer, Buffer, Blob, or File) the array's first item will be a string with packet-relevant metadata and JSON with placeholders where the binary data was held in the initial packet. The remaining items will be the raw binary data to fill in the placeholders post-decoding.
The callback function is called with the encoded array as its only argument. In the socket.io-parser implementation, the callback writes each item in the array to engine.io for transport. The expectation for any implementation is that each item in the array is transported sequentially.
An object that decodes data from engine.io into complete socket.io packets.
The expected workflow for using the Decoder is to call theDecoder#addmethod upon receiving any encoding from engine.io (in the sequential order in which the encodings are received) and to listen to the Decoder's 'decoded' events to handle fully decoded packets.
Decodes a single encoded object from engine.io transport. In the case of a non-binary packet, the one encoding argument is used to reconstruct the full packet. If the packet is of typeBINARY_EVENTorACK, then additional calls to add are expected, one for each piece of binary data in the original packet. Once the final binary data encoding is passed to add, the full socket.io packet is reconstructed.
After a packet is fully decoded, the Decoder emits a 'decoded' event (via Emitter) with the decoded packet as the sole argument. Listeners to this event should treat the packet as ready-to-go.
Deallocates the Decoder instance's resources. Should be called in the event of a disconnect mid-decoding, etc. to prevent memory leaks.
Array of packet type keys.
Each packet is represented as a vanillaObjectwith anspkey that indicates what namespace it belongs to (see "Multiplexing") and atypekey that can be one of the following:
Packet#CONNECT(0)
Packet#DISCONNECT(1)
Packet#EVENT(2)
Packet#ACK(3)
Packet#ERROR(4)
Packet#BINARY_EVENT(5)
Packet#BINARY_ACK(6)
data(Array) a list of arguments, the first of which is the event name. Arguments can contain any type of field that can result ofJSONdecoding, including objects and arrays of arbitrary size.
id(Number) if theididentifier is present, it indicates that the server wishes to be acknowledged of the reception of this event.
data(Array) seeEVENTdata, but with addition that any of the arguments may contain non-JSON arbitrary binary data. For encoding, binary data is considered either a Buffer, ArrayBuffer, Blob, or File. When decoding, all binary data server-side is a Buffer; on modern clients binary data is an ArrayBuffer. On older browsers that don't support binary, every binary data item is replaced with an object like so:{base64: true, data: }. When aBINARY_EVENTorACKpacket is initially decoded, all of the binary data items will be placeholders, and will be filled by additional calls toDecoder#add.
id(Number) seeEVENTid.
data(Array) seeEVENTdata. Encoded as string like theEVENTtype above. Should be used when an ACK function is not called with binary data.
id(Number) seeEVENTid.
data(Array) seeACKdata. Used when the arguments for an ACK function contain binary data; encodes packet in theBINARY_EVENTstyle documented above.
id(Number) seeEVENTid.
data(Mixed) error data
The socket.io protocol can be delivered over a variety of transports.socket.io-clientis the implementation of the protocol for the browser and Node.JS overengine.io-client.
socket.iois the server implementation of the protocol overengine.io.
Socket.IO has built-in multiplexing support, which means that each packet always belongs to a givennamespace, identified by a path string (like/this). The corresponding key in thePacketobject isnsp.
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 aCONNECTpacket to the/namespace).
In order to support multiplexing of multiple sockets under the same transport, additionalCONNECTpackets can be sent by the client to arbitrary namespace URIs (eg:/another).
When the server responds with aCONNECTpacket to the corresponding namespace, the multiplexed socket is considered connected.
Alternatively, the server can respond with anERRORpacket 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 aCONNECTpacket is received by the server for a givennsp, the client can then send and receiveEVENTpackets. If any of the parties receives anEVENTpacket with anidfield, anACKpacket is expected to confirm the reception of said packet.
MIT
