Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 240 lines (169 sloc) 5.769 kb
5c2217f @tj Initial commit
authored
1
2 # Super Sockets
3
4 Super Sockets is a message-oriented socket library for node.js heavily inspired by zeromq.
5
00b5dcc @tj add some docs
authored
6 ## Installation
7
8 $ npm install super-sockets
9
5c2217f @tj Initial commit
authored
10 ## Features
11
12 - message oriented
13 - automated reconnection
14 - light-weight wire protocol
15 - light-weight implementation (~300 SLOC)
16 - supports arbitrary binary message (msgpack, json, BLOBS, etc)
17 - supports JSON messages
18 - push / pull pattern
19 - pub / sub pattern
20 - event emitter pattern
21
22 ## Push / Pull
23
0e7ade0 @tj tweak docs
authored
24 `PushSocket`s distribute messages round-robin:
5c2217f @tj Initial commit
authored
25
26 ```js
b3cabbb @tj fix readme example
authored
27 var ss = require('super-sockets')
28 , sock = ss.socket('push');
5c2217f @tj Initial commit
authored
29
30 sock.bind(3000);
31 console.log('push server started');
32
33 setInterval(function(){
34 sock.send('hello');
35 }, 150);
36 ```
37
0e7ade0 @tj tweak docs
authored
38 Receiver of `PushSocket` messages:
5c2217f @tj Initial commit
authored
39
40 ```js
b3cabbb @tj fix readme example
authored
41 var ss = require('super-sockets')
42 , sock = ss.socket('pull');
5c2217f @tj Initial commit
authored
43
b3cabbb @tj fix readme example
authored
44 sock.connect(3000);
5c2217f @tj Initial commit
authored
45
b3cabbb @tj fix readme example
authored
46 sock.on('message', function(msg){
47 console.log(msg.toString());
48 });
5c2217f @tj Initial commit
authored
49 ```
50
51 ## Pub / Sub
52
0e7ade0 @tj tweak docs
authored
53 `PubSocket`s send messages to all subscribers without queueing:
5c2217f @tj Initial commit
authored
54
55 ```js
b3cabbb @tj fix readme example
authored
56 var ss = require('super-sockets')
57 , sock = ss.socket('pub');
5c2217f @tj Initial commit
authored
58
59 sock.bind(3000);
60 console.log('pub server started');
61
62 setInterval(function(){
63 sock.send('hello');
64 }, 500);
65 ```
66
0e7ade0 @tj tweak docs
authored
67 `SubSocket` provides selective reception of messages from a `PubSocket`:
5c2217f @tj Initial commit
authored
68
69 ```js
b3cabbb @tj fix readme example
authored
70 var ss = require('super-sockets')
71 , sock = ss.socket('sub');
5c2217f @tj Initial commit
authored
72
73 sock.connect(3000);
74
75 sock.on('message', function(msg){
76 console.log(msg.toString());
77 });
78 ```
79
80 ## EmitterSocket
81
82 `EmitterSocket`'s send and receive messages behaving like regular node `EventEmitter`s.
a954967 @tj add json codec for emitter socket docs
authored
83 This is achieved by using pub / sub sockets behind the scenes, automatically assigned
84 the "json" codec. Currently we simply choose define the `EmitterSocket` as a `PubSocket` if you `.bind()`, and `SubSocket` if you `.connect()`, providing the natural API you're used to:
5c2217f @tj Initial commit
authored
85
86 server.js:
87
88 ```js
b3cabbb @tj fix readme example
authored
89 var ss = require('super-sockets')
90 , sock = ss.socket('emitter');
5c2217f @tj Initial commit
authored
91
92 sock.bind(3000);
93 console.log('pub server started');
94
95 setInterval(function(){
96 sock.emit('login', { name: 'tobi' });
97 }, 500);
98 ```
99
100 client.js:
101
102 ```js
b3cabbb @tj fix readme example
authored
103 var ss = require('super-sockets')
104 , sock = ss.socket('emitter');
5c2217f @tj Initial commit
authored
105
106 sock.connect(3000);
107 console.log('sub client connected');
108
109 sock.on('login', function(user){
110 console.log('%s signed in', user.name);
111 });
112 ```
113
114 ## Protocol
115
116 The wire protocol is simple and very much zeromq-like, where `<length>` is
05fbb1f @tj refactor framing
authored
117 a BE 24 bit unsigned integer representing a maximum length of roughly ~16mb. The `<meta>`
1004e8b @tj add codec docs
authored
118 data byte is currently only used to store the codec, for example "json" is simply `1`,
119 in turn JSON messages received on the client end will then be automatically decoded for
120 you by selecting this same codec.
5c2217f @tj Initial commit
authored
121
122 ```
123 octet: 0 1 2 3 <length>
124 +------+------+------+------+------------------...
125 | meta | <length> | data ...
126 +------+------+------+------+------------------...
127 ```
128
05fbb1f @tj refactor framing
authored
129 Thus 5 bytes is the smallest message super sockets supports at the moment. Later if
130 necessary we can use the meta to indicate a small message and ditch octet 2 and 3
131 allowing for 3 byte messages.
132
43fbdf1 @tj add ss.codec.define() docs
authored
133 ## Codecs
134
135 To define a codec simply invoke the `ss.codec.define()` method, for example
136 here is the JSON codec:
137
138 ```js
139 var ss = require('super-sockets');
140
141 ss.codec.define('json', {
142 encode: JSON.stringify,
143 decode: JSON.parse
144 });
145 ```
146
147 __Note:__ codecs must be defined on both the sending and receiving ends, otherwise
148 super sockets cannot properly decode the messages. You may of course ignore this
149 feature all together and simply pass encoded data to `.send()`.
150
91f026a @tj add benchmarks to readme
authored
151 ## Performance
152
8a27a53 @tj add more bm results to readme
authored
153 I haven't profiled or tuned anything yet but so far for on my macbook air:
154
155 1 byte messages:
156
157 ```
158
159 mean: 61986 ops/s
160 median: 45512 ops/s
161
162 ```
163
164 1k messages:
165
166 ```
167
168 mean: 56958 ops/s
169 median: 45995 ops/s
170
171 ```
172
173 20k messages:
91f026a @tj add benchmarks to readme
authored
174
175 ```
176
8a27a53 @tj add more bm results to readme
authored
177 mean: 7597 ops/s
178 median: 4819 ops/s
91f026a @tj add benchmarks to readme
authored
179
180 ```
181
00b5dcc @tj add some docs
authored
182 ## What's it good for?
183
a0ea3ab @tj add more docs
authored
184 Super sockets are not meant to combat zeromq nor provide feature parity,
00b5dcc @tj add some docs
authored
185 but provide a nice solution when you don't need the insane
186 nanosecond latency or language interoperability that zeromq provides
187 as super sockets do not rely on any third-party compiled libraries.
188
5c2217f @tj Initial commit
authored
189 ## Running tests
190
191 ```
192 $ npm install
193 $ make test
194 ```
195
196 ## Todo
197
198 - more tests
199 - code cov
200 - acks
656c9e4 @tj add todo
authored
201 - make socket options configurable
b9746d3 @tj add todo
authored
202 - clean up queue / sock
13e1248 @tj add todo
authored
203 - benchmarks
5c2217f @tj Initial commit
authored
204 - emitter style on top of pubsub with multipart
205 - pluggable codecs
206 - weighted fair queuing
207 - use mocha for tests
05fbb1f @tj refactor framing
authored
208 - multipart frames
209 - batching
8e0e544 @tj add todo
authored
210 - binary support for EmitterSocket (requires multipart)
5c2217f @tj Initial commit
authored
211 - subscriptions
05fbb1f @tj refactor framing
authored
212 - profiling / applying basic perf rules (pre-define members etc, measure results)
5c2217f @tj Initial commit
authored
213 - ...
214
215 ## License
216
217 (The MIT License)
218
219 Copyright (c) 2012 TJ Holowaychuk &lt;tj@vision-media.ca&gt;
220
221 Permission is hereby granted, free of charge, to any person obtaining
222 a copy of this software and associated documentation files (the
223 'Software'), to deal in the Software without restriction, including
224 without limitation the rights to use, copy, modify, merge, publish,
225 distribute, sublicense, and/or sell copies of the Software, and to
226 permit persons to whom the Software is furnished to do so, subject to
227 the following conditions:
228
229 The above copyright notice and this permission notice shall be
230 included in all copies or substantial portions of the Software.
231
232 THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
233 EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
234 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
235 IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
236 CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
237 TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
238 SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
239
Something went wrong with that request. Please try again.