Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 177 lines (128 sloc) 4.075 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
6 ## Features
7
8 - message oriented
9 - automated reconnection
10 - light-weight wire protocol
11 - light-weight implementation (~300 SLOC)
12 - supports arbitrary binary message (msgpack, json, BLOBS, etc)
13 - supports JSON messages
14 - push / pull pattern
15 - pub / sub pattern
16 - event emitter pattern
17
18 ## Push / Pull
19
20 `PushSocket`s distribute messages round-robin.
21
22 ```js
23 var ss = require('super-sockets');
24 var sock = ss.socket('push');
25
26 sock.bind(3000);
27 console.log('push server started');
28
29 setInterval(function(){
30 process.stdout.write('.');
31 sock.send('hello');
32 }, 150);
33 ```
34
35 Receiver of `PushSocket` messages.
36
37 ```js
38 var ss = require('../../')
39 , sock = ss.socket('push');
40
41 sock.bind(3000);
42 console.log('push server started');
43
44 setInterval(function(){
45 process.stdout.write('.');
46 sock.send('hello');
47 }, 150);
48 ```
49
50 ## Pub / Sub
51
52 `PubSocket`s send messages to all subscribers without queueing.
53
54 _pub.js_:
55
56 ```js
57 var ss = require('super-sockets');
58 var sock = ss.socket('pub');
59
60 sock.bind(3000);
61 console.log('pub server started');
62
63 setInterval(function(){
64 console.log('sending');
65 sock.send('hello');
66 }, 500);
67 ```
68
69 `SubSocket` provides selective reception of messages from a `PubSocket`.
70
71 _sub.js_:
72
73 ```js
74 var ss = require('super-sockets');
75 var sock = ss.socket('sub');
76
77 sock.connect(3000);
78
79 sock.on('message', function(msg){
80 console.log(msg.toString());
81 });
82 ```
83
84 ## EmitterSocket
85
86 `EmitterSocket`'s send and receive messages behaving like regular node `EventEmitter`s.
87 This is achieved by using pub / sub sockets behind the scenes. Currently we simply choose
88 define the `EmitterSocket` as a `PubSocket` if you `.bind()`, and `SubSocket` if you `.connect()`,
89 providing the natural API you're used to:
90
91 server.js:
92
93 ```js
94 var ss = require('super-sockets');
95 var sock = ss.socket('emitter');
96
97 sock.bind(3000);
98 console.log('pub server started');
99
100 setInterval(function(){
101 sock.emit('login', { name: 'tobi' });
102 }, 500);
103 ```
104
105 client.js:
106
107 ```js
108 var ss = require('super-sockets');
109 var sock = ss.socket('emitter');
110
111 sock.connect(3000);
112 console.log('sub client connected');
113
114 sock.on('login', function(user){
115 console.log('%s signed in', user.name);
116 });
117 ```
118
119 ## Protocol
120
121 The wire protocol is simple and very much zeromq-like, where `<length>` is
122 a 24 bit unsigned integer, representing a maximum length of 2^24, roughly ~16mb,
123 so you should be good :p
124
125 ```
126 octet: 0 1 2 3 <length>
127 +------+------+------+------+------------------...
128 | meta | <length> | data ...
129 +------+------+------+------+------------------...
130 ```
131
132 ## Running tests
133
134 ```
135 $ npm install
136 $ make test
137 ```
138
139 ## Todo
140
141 - more tests
142 - code cov
143 - acks
144 - emitter style on top of pubsub with multipart
145 - pluggable codecs
146 - weighted fair queuing
147 - use mocha for tests
148 - multipart
149 - subscriptions
150 - ...
151
152 ## License
153
154 (The MIT License)
155
156 Copyright (c) 2012 TJ Holowaychuk &lt;tj@vision-media.ca&gt;
157
158 Permission is hereby granted, free of charge, to any person obtaining
159 a copy of this software and associated documentation files (the
160 'Software'), to deal in the Software without restriction, including
161 without limitation the rights to use, copy, modify, merge, publish,
162 distribute, sublicense, and/or sell copies of the Software, and to
163 permit persons to whom the Software is furnished to do so, subject to
164 the following conditions:
165
166 The above copyright notice and this permission notice shall be
167 included in all copies or substantial portions of the Software.
168
169 THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
170 EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
171 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
172 IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
173 CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
174 TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
175 SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
176
Something went wrong with that request. Please try again.