Once the transport's connection is established, all the communication between the client and server happens using messaging over the socket. The messages need to be encoded in the format specified by socket.io.
This format enables socket.io to determine the type of the message and the data sent in the message, and some metadata useful for operation. The message format is [type] : [id ('+')] : [endpoint] (: [data]).
typeis a single digit integer, specifying what type of message it is.idis the message ID, which is an incremental integer; it is used for ACKs. It is optional.- The
+sign, if present, tells socket.io not to handle the ACKs, as the application intends to handle it. endpointis the socket endpoint that the message is intended to be delivered to. This is optional and is used when multiplexing the socket for namespacing. If omitted, the message will be sent to the default socket.datais the associated data to be delivered to the socket. In the case of messages, it is treated as plain text, while in the case of events, it will be parsed as JSON.
In the coming section, we will see what the types of messages are.
When the type is zero (0), the message is a disconnect signal. This will tell socket.io to close the connection and the mentioned socket. If the endpoint is not specified, the message will be sent to the default socket, which will cause the whole socket to be closed and all the endpoints on that socket will be terminated. For example:
- Message:
0– The result is that the socket is closed and all the connections/endpoints are terminated. - Message:
0::/endpoint– The socket connection to/endpointwill be closed and no messages can be sent to or from that endpoint. Other endpoints will continue to operate.
This message is only used for multiplexing, and is sent from the client to the server to open a new connection. Thus, this message must always have an endpoint. The first (default) socket connection is established by the handshake explained earlier. The endpoint may be followed by query parameters in a URL query format. If the connection is successful, the server will echo the same message, else the server can send an error message. For example:
- Message:
1::/endpoint– Requests the server to open a multiplexed socket to the endpoint. - Message:
0::/endpoint?param=one– Requests the server to open a multiplexed socket to the endpoint, passing a parameter calledparamwith the valueone.
This is the heartbeat message. It must be sent from the client to the server within the timeout negotiated during the handshake. The server will reply with a heartbeat message too. In this case, we don't have an endpoint and nor is any other information required. This is because it serves the whole socket. For example:
- Message:
2– Sends a heartbeat message to the other end.
This is the message sent over the socket. In the API, this message will be sent when you are using socket.send, and will result in a message event on the receiving end. This message will carry data, treating it as plan text. For example:
- Message:
3:1::Some message– This will send a message to the other end, where the message event handler will be triggered with theSome messagemessage in the event data. - Message:
3:1:/endpoint:Some message– Again, the message will be sent to other end of the socket, but on the multiplexed endpoint.
This is similar to sending the message, but in this case the message has to be serialized using JSON, and it will be parsed at the other end before being sent to the handler. In version 0.6, this was done using the same API as send() for message, just passing a JSON message instead of a string message. But since this introduces a performance penalty over sending plain text from version 0.7 onwards, we have to use the json flag to send a JSON message; for example, socket.json.send. For example:
- Message:
4:1::{"some":"content"}– Sends the JSON message to the other end of the socket.
The Event message is a special kind of JSON message that is used to send events over the socket. In events, the data payload is of the form {"name":"eventName", "args":{"some":"content"}}.
Here, name is the name of the event and args are the parameters to be sent to the handler. The socket.emit call is used to send events in the applications.
The following event names are reserved and cannot be used in applications:
messageconnectdisconnectopencloseerrorretryreconnect
For example:
- Message:
5:1::{"name": "myEvent", "args":{"some": "data"}– The result is that the event will be sent to the other end and the appropriate event handler will be invoked, passing the args to it.
The acknowledgment (ACK) message will be sent when the message is received, with ACK request enabled; or, it can be sent out by the application. The data section in the ACK message can be the message ID for the message that is being acknowledged. If the message ID is followed by + and additional data, it is treated as an event packet. For example:
- Message:
6:::1– Sends an acknowledgment for the receipt of a message with ID1. - Message:
6:::1+["A", "B"]– This will send an acknowledgment for the message along with the data.
This is sent by the server in case there's an error, such as failure during the processing of a connect request to an endpoint. The data section of this message will contain the error message and, optionally, advice, separated by the + sign. For example:
- Message:
7:::Unauthorized– The result is that the error will be sent to the client.