1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
|
# engine.io-parser
[](http://travis-ci.org/socketio/engine.io-parser)
[](http://badge.fury.io/js/engine.io-parser)
This is the JavaScript parser for the engine.io protocol encoding,
shared by both
[engine.io-client](https://github.com/socketio/engine.io-client) and
[engine.io](https://github.com/socketio/engine.io).
## How to use
### Standalone
The parser can encode/decode packets, payloads, and payloads as binary
with the following methods: `encodePacket`, `decodePacket`, `encodePayload`,
`decodePayload`, `encodePayloadAsBinary`, `decodePayloadAsBinary`.
The browser-side parser also includes `encodePayloadAsArrayBuffer` and `encodePayloadAsBlob`.
Example:
```js
var parser = require('engine.io-parser');
var data = new Buffer(5);
for (var i = 0; i < data.length; i++) { data[i] = i; }
parser.encodePacket({ type: 'message', data: data }, function(encoded) {
var decodedData = parser.decodePacket(encoded); // { type: 'message', data: data }
});
```
### With browserify
Engine.IO Parser is a commonjs module, which means you can include it by using
`require` on the browser and package using [browserify](http://browserify.org/):
1. install the parser package
```shell
npm install engine.io-parser
```
1. write your app code
```js
var parser = require('engine.io-parser');
var testBuffer = new Int8Array(10);
for (var i = 0; i < testBuffer.length; i++) testBuffer[i] = i;
var packets = [{ type: 'message', data: testBuffer.buffer }, { type: 'message', data: 'hello' }];
parser.encodePayload(packets, function(encoded) {
parser.decodePayload(encoded,
function(packet, index, total) {
var isLast = index + 1 == total;
if (!isLast) {
var buffer = new Int8Array(packet.data); // testBuffer
} else {
var message = packet.data; // 'hello'
}
});
});
```
1. build your app bundle
```bash
$ browserify app.js > bundle.js
```
1. include on your page
```html
<script src="/path/to/bundle.js"></script>
```
## Features
- Runs on browser and node.js seamlessly
- Runs inside HTML5 WebWorker
- Can encode and decode packets
- Encodes from/to ArrayBuffer or Blob when in browser, and Buffer or ArrayBuffer in Node
## API
Note: `cb(type)` means the type is a callback function that contains a parameter of type `type` when called.
### Node
- `encodePacket`
- Encodes a packet.
- **Parameters**
- `Object`: the packet to encode, has `type` and `data`.
- `data`: can be a `String`, `Number`, `Buffer`, `ArrayBuffer`
- `Boolean`: optional, binary support
- `Function`: callback, returns the encoded packet (`cb(String)`)
- `decodePacket`
- Decodes a packet. Data also available as an ArrayBuffer if requested.
- Returns data as `String` or (`Blob` on browser, `ArrayBuffer` on Node)
- **Parameters**
- `String` | `ArrayBuffer`: the packet to decode, has `type` and `data`
- `String`: optional, the binary type
- `encodeBase64Packet`
- Encodes a packet with binary data in a base64 string (`String`)
- **Parameters**
- `Object`: the packet to encode, has `type` and `data`
- `Function`: callback, returns the base64 encoded message (`cb(String)`)
- `decodeBase64Packet`
- Decodes a packet encoded in a base64 string.
- **Parameters**
- `String`: the base64 encoded message
- `String`: optional, the binary type
- `encodePayload`
- Encodes multiple messages (payload).
- If any contents are binary, they will be encoded as base64 strings. Base64
encoded strings are marked with a b before the length specifier
- **Parameters**
- `Array`: an array of packets
- `Boolean`: optional, binary support
- `Function`: callback, returns the encoded payload (`cb(String)`)
- `decodePayload`
- Decodes data when a payload is maybe expected. Possible binary contents are
decoded from their base64 representation.
- **Parameters**
- `String`: the payload
- `String`: optional, the binary type
- `Function`: callback, returns (cb(`Object`: packet, `Number`:packet index, `Number`:packet total))
- `encodePayloadAsBinary`
- Encodes multiple messages (payload) as binary.
- **Parameters**
- `Array`: an array of packets
- `Function`: callback, returns the encoded payload (`cb(Buffer)`)
- `decodePayloadAsBinary`
- Decodes data when a payload is maybe expected. Strings are decoded by
interpreting each byte as a key code for entries marked to start with 0. See
description of encodePayloadAsBinary.
- **Parameters**
- `Buffer`: the buffer
- `String`: optional, the binary type
- `Function`: callback, returns the decoded packet (`cb(Object)`)
### Browser
- `encodePayloadAsArrayBuffer`
- Encodes multiple messages (payload) as binary.
- **Parameters**
- `Array`: an array of packets
- `Function`: callback, returns the encoded payload (`cb(ArrayBuffer)`)
- `encodePayloadAsBlob`
- Encodes multiple messages (payload) as blob.
- **Parameters**
- `Array`: an array of packets
- `Function`: callback, returns the encoded payload (`cb(Blob)`)
## Tests
Standalone tests can be run with `make test` which will run both node.js and browser tests.
Browser tests are run using [zuul](https://github.com/defunctzombie/zuul).
(You must have zuul setup with a saucelabs account.)
You can run the tests locally using the following command:
```
./node_modules/.bin/zuul --local 8080 -- test/index.js
```
## Support
The support channels for `engine.io-parser` are the same as `socket.io`:
- irc.freenode.net **#socket.io**
- [Google Groups](http://groups.google.com/group/socket_io)
- [Website](http://socket.io)
## Development
To contribute patches, run tests or benchmarks, make sure to clone the
repository:
```bash
git clone git://github.com/LearnBoost/engine.io-parser.git
```
Then:
```bash
cd engine.io-parser
npm install
```
See the `Tests` section above for how to run tests before submitting any patches.
## License
MIT
|
