LearnBoost/engine.io-protocol — pull request #15 by rase- (2014-02-01 01:02:19+00:00)
Title: Binary support

This pull request answers to the issue of sending binary data over engine.io. Please take a look at the engine.io pull request for other details than the protocol.

With these changes binary data can be sent from the server to the client, and the other way around. The API for sending binary data is the same as for sending utf-8 strings, but binary types are detected. The data is then received as binary on the other end.

To achieve sending of binary, binary data needs to be encoded and decoded like string are now handled. This is accomplished by using a similar method to encoding individual packets as with strings: the first byte of the encoding contains a number representing the packet type id, and the rest has the actual binary message if present. Individual packet encodings are used when encoding an entire payload for individual packets, as well as directly for sending binary data over WebSockets.

To encode multiple binary packets into a payload, they are concatenated by adding a descriptor field in front of every individual packet encoding containing first a single byte that has either a number 0 for string and 1 for binary (strings and binary can be mixed as payload). The descriptor field then has a variable number of bytes interpreted as single numbers between 0-9, that together represent as a string the number of bytes that the actual message contains. The length field and the actual message are separated by a separator value of 255.

The way string are encoded with binary messages is based on char codes of the characters in the string. Basically the string is transformed into binary by taking each individual character's char code, and representing that in the binary as a single unsigned integer. In the decoding step the first byte of the descriptor fields tells us that we need to interpret the actual data as char codes for a string. This payload encoding method is used for XHR polling when the XHR2 supported responseType feature is present.

For browsers and transports that don't support sending binary data directly, the traditional payload encoding method is used. However, when the payload contains a packet with binary data, the actual data field is base64 encoded into a string. The encoding for those packets is the same, but is prefixed with a b character to signify base64 encoding: b.