Permalink
Browse files

initial

  • Loading branch information...
0 parents commit f5d3f5f5b2a938415b4ed5e22b258f3a0e4e91d1 @youurayy committed Feb 26, 2012
Showing with 669 additions and 0 deletions.
  1. +29 −0 LICENSE
  2. +228 −0 README.md
  3. +184 −0 lib/ws-rpc.js
  4. +1 −0 optjs.sh
  5. +26 −0 package.json
  6. +200 −0 public/ws-rpc-client.js
  7. +1 −0 public/ws-rpc-client.min.js
29 LICENSE
@@ -0,0 +1,29 @@
+Copyright: Hiroshi Ichikawa <http://gimite.net/en/>
+Copyright: Juraj Vitko (@ypocat)
+Mostly repackaging of https://github.com/gimite/web-socket-js
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions
+are met:
+
+ * Redistributions of source code must retain the above
+ copyright notice, this list of conditions and the following
+ disclaimer.
+
+ * Redistributions in binary form must reproduce the above
+ copyright notice, this list of conditions and the following
+ disclaimer in the documentation and/or other materials
+ provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER “AS IS” AND ANY
+EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER BE
+LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY,
+OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR
+TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF
+THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+SUCH DAMAGE.
228 README.md
@@ -0,0 +1,228 @@
+# ws-rpc: lightweight RPC support for the [ws](https://github.com/einaros/ws) WebSocket server
+
+### Server
+
+Install dependencies:
+
+ npm install express
+ npm install ws
+ npm install ws-rpc
+ npm install ws-flash-client
+ npm install policyfile
+
+##### Complete example with Express, ws, and the Flash client shim support:
+
+Notes:
+
+- `args` stands for multiple arguments, e.g. `arg1, arg2, arg3`
+- messages with callbacks can only be used when messaging a single client
+
+```js
+var prod = process.env.NODE_ENV === 'production';
+var app = require('express').createServer();
+var wss = new (require('ws').Server)({ server: app });
+var wsrpc = require('ws-rpc').extend(wss);
+var wsflash = require('ws-flash-client');
+require('policyfile').createServer().listen(prod ? 843 : 10843, app);
+
+app.configure(function() {
+ // configure other stuff like express globals, jade, stylus, etc.
+ // ...
+
+ // configure the ws-rpc middleware:
+ app.use(wsrpc.middleware(express));
+
+ // configure the ws-flash-client middleware:
+ app.use(wsflash.middleware(express));
+
+ // static file handling must come afterwards:
+ app.use(express.static(pub));
+
+ // bind node to a port
+ app.listen(prod ? 80 : 1234);
+});
+
+// create/get a named room (channel)
+var myRoom = wss.room('myRoom');
+
+// handle a new client connection
+wss.on('connect', function(client) {
+
+ // add client to a room
+ myRoom.add(client);
+
+ // message the client
+ client.message('some message', args);
+
+ // message the client with callback
+ client.message('some message', args, function(err, args) {
+ if(err)
+ // ...
+ });
+
+ //client.on(... <-- not here, see below
+});
+
+// handle message from a client without a callback
+wss.on('some message', function(client, args) {
+
+ // ...
+});
+
+// handle message from a client with a callback
+wss.on('some message', function(client, args, cb) {
+
+ // ...
+
+ // call the callback (should use node convention but not mandatory)
+ cb(null, 'ok');
+});
+
+// handle client disconnection
+wss.on('disconnect', function(client) {
+
+ //myRoom.remove(client); <- not necessary, this is done automatically
+
+ // example: broadcast too all client's rooms
+ for(id in client.rooms)
+ client.rooms[id].message('some message', args);
+});
+
+// message all clients connected to the server
+wss.message('some message', args);
+
+// msg all clients in a room
+myRoom.message('some message', args);
+
+// and don't forget this if you don't want your Node to crash on an error:
+// if the error comes from a client, the client is passed as second parameter
+wss.on('error', function(e, client) {
+ console.log(client ? 'client' : 'server', e);
+});
+```
+
+Binary messages are not handled by the RPC extension, so you can handle them separately using the classic `ws` API.
+
+Also, if you want to intercept the raw string messages and do your own handling in some cases, you can leave out the `require('ws-rpc').extend(wss);` line above, and do the following:
+
+```js
+wss.on('connection', function(client) { // notice: "connection" vs "connect"
+ client.on('message', function(data, flags) {
+ if(is_my_message(data)) {
+ // handle the raw message here
+ // ...
+ // notify the RPC extension that this message was already handled
+ flags.handled = true;
+ }
+ // otherwise the message will be handled as RPC
+ });
+});
+
+// only setup the RPC extension after the above
+require('ws-rpc').extend(wss);
+```
+
+### Browser
+
+In your HTML page ([JADE](http://jade-lang.com/) syntax shown):
+
+ !!! 5
+ html
+ head
+ meta(http-equiv='X-UA-Compatible', content='IE=Edge,chrome=1')
+ //if lt IE 8
+ script(src='http://cdnjs.cloudflare.com/ajax/libs/json2/20110223/json2.min.js')
+ script(src='http://ajax.googleapis.com/ajax/libs/jquery/1.7.1/jquery.min.js')
+ script(src='/ws-rpc-client.min.js')
+ script(src='/ws-flash.min.js')
+ script(src='/myclientcode.js')
+ body
+ #msg
+
+Complete example with the Flash client shim support (for full usage and options please see [ws-flash-client](https://github.com/ypocat/ws-flash-client)):
+
+```js
+$(function() {
+
+ $.wsFlashClientInit({}, function(err) {
+ if(err)
+ return log('no websocket support');
+
+ // create the client (will use WebSocket object on the background)
+ // param1: url
+ // param2 (optional): protocols, see http://dev.w3.org/html5/websockets/#websocket
+ // param3 (optional): connection timeout in ms (default 4s), set to -1 to disable automatic reconnecting
+ // param4 (optional): reconnection wait timeout (default 1s)
+ var ws = new WebSocketRPC('ws://' + window.location.host + '/');
+
+ // handle a message from the server
+ ws.on('some message', function(args) {
+
+ // ...
+ });
+
+ // handle a message from the server with a callback
+ ws.on('some message', function(args, cb) {
+
+ // ...
+
+ cb(null, 'hello from client');
+
+ // or, in the case of an error:
+
+ cb(new Error('some problem'));
+ });
+
+ // message the server
+ ws.message('some message', args);
+
+ // message the server with a callback
+ ws.message('some message', args, function(err, args) {
+ if(err)
+ // ...
+ });
+
+ // disconnect from the server
+ // param1 (optional): disable automatic reconnection
+ ws.disconnect(true);
+
+ // connected event
+ ws.on('open', function(world) {
+ log('connected');
+
+ // access the WebSocket if needed:
+ //ws.socket ... <- will be null when disconnected, and then a new one created
+ });
+
+ // disconnected event
+ ws.on('close', function(world) {
+ log('disconnected');
+ });
+
+ // error event
+ ws.on('error', function(e) {
+ log(e.stack || e);
+ });
+ });
+
+ // just an example
+ function log(s) {
+ var m = $('#msg');
+ m.text(m.text() + '\n' + s);
+ }
+});
+```
+
+Usage without `ws-flash-client`:
+
+```js
+
+var ws = new WebSocketRPC('ws://' + window.location.host + '/');
+
+// ..and the same operations as above..
+
+```
+
+### License
+
+New BSD License.
Oops, something went wrong.

0 comments on commit f5d3f5f

Please sign in to comment.