JSON WebSocket is a lightweight wrapper around the websocket implementation. Event types and objects are automatically translated to and from JSON, and emitted as events when received.
Installation
Install JsonWebSocket using Node Package Manager (npm):
npm install json-websocket
Usage
Example client (found in examples/client.js
)
var main = require('../lib/main');
var client = main.client({ host: 'localhost', port: 8000, verbose: true });
client.connect.on('connect', function() {
client.send('greeting', 'Websocket client here');
});
client.on('add', function(v1, v2, callback) {
callback(v1 + v2);
});
setTimeout(function() {
client.disconnect();
}, 1000);
Example server (found in examples/server.js
)
var http = require('http').createServer();
var main = require('../lib/main');
var server = main.server({ httpServer: http, verbose: true });
server.on('multiply', function(clientId, v1, v2, callback) {
callback(v1 * v2);
});
server.on('tick', function(clientId, time) {
//Process "tick" event here
});
server.connect.on('connect', function(clientId) {
server.send(clientId, 'greet', 'Greetings, client #' + clientId);
});
server.connect.on('disconnect', function(clientId) {
//Client disconnected
});
http.listen(8000);
Example browser client (from examples/browser.html
):
var client = jsonSocket({
host: 'localhost',
port: 8000,
verbose: true
});
client.connect.on('connect', function() {
client.send('greeting', 'Websocket client here');
});
client.on('add', function(v1, v2, callback) {
callback(v1 + v2);
});
You must first build the browser bundle with ./browserify.sh
before browser.html will work.
API
Server
To create a server, use require('json-websocket').server(opts);
.
Options:
httpServer
: A http.Server object that the websocket will bind topath
: The URL path the websocket will listen on in the server. Defaults to/
verbose
: Any truthy value will enable debug logging toconsole.log
protocol
: Name of the websocket protocol to support. Defaults to'json-websocket'
maxListeners
: Controls the maximum number of listeners that can be attached to the resulting EventEmitter. Use0
for unlimited. Defaults to10
This returns an Event Emitter with the following properties:
Event: 'js:connect'###
function (clientId) { }
Emitted each time a new client successfully connects.
Event: 'js:disconnect'###
function (clientId) { }
Emitted each time a client disconnects.
Event: 'js:error'###
function (err) { }
Emitted on errors.
Event: *###
function (clientId, ...) { }
All messages received by clients are emitted as events with the "type" of the sent message.
server.send(clientId, type, ...)###
Send a message to the given client of the given type. type
must be a String
and cannot start with "js:". Any additional arguments provided to this function will be transmitted to the client and attached to the emitted event.
server.clients###
An object mapping client identifiers to the underlaying websocket connections.
server.numClients###
The number of currently connected clients.
server.isReady(clientId)###
Returns true
if there is a connected client with the given identifier that is in the ready state and has no currently buffered outgoing data, false
otherwise.
Client
To create a client, use require('json-websocket').client(opts);
.
Options:
hostname
: The host that the client will attempt to connect to. Defaults tolocalhost
port
: The port that the client will attempt to connect to. Defaults to80
path
: The URL path that the client will attempt to connect to. Defaults to/
verbose
: Any truthy value will enable debug logging toconsole.log
protocol
: Name of the websocket protocol to request. Defaults to'json-websocket'
maxListeners
: Controls the maximum number of listeners that can be attached to the resulting EventEmitter. Use0
for unlimited. Defaults to10
Event: 'js:connect'###
function () { }
Emitted when the socket successfully connects.
Event: 'js:disconnect'###
function () { }
Emitted when the socket is closed.
Event: 'js:error'###
function (err) { }
Emitted on a connection failure.
Event: *###
All messages received by the server are emitted as events with the "type" of the sent message.
client.send(type, ...)###
Send a message to the server with the given type. type
must be a String
and cannot start with "js:". Any additional arguments will be sent along to the server and attached to the emitted event.
Messages sent before the js:connect
event has been emitted will be queued and sent once the connection is established.
client.disconnect()###
Closes the websocket connection.
client.isReady()###
Returns true
if the websocket connection is established, ready, and has no buffered outgoing data, false
otherwise.
Browser
JSON WebSocket can also be used in the browser with no dependency on the node websocket module relying instead on the browser's implementation.
In order to do this, you should include ./lib/browser.js
using a CommonJS bundler. For instance, using browserify:
browserify ./lib/browser.js -s jsonSocket -o bundle.js
or simply running the included ./browserify.sh
script. (Note that browserify must be installed on your system globally for this script to work.)
Pointing a web browser to ./examples/browser.html
on the local filesystem after generating the browser bundle will load an empty test page that will attempt to connect to the example server.
The client
object in the global namespace is the connected json-socket object and the jsonSocket
function in the global namespace is the method to create additional client sockets.
The client socket object has the same events and methods as the Node JS client object.
Testing
Run tests using Node Package Manager (npm):
npm test
License
Copyright (c) 2013 Isaac Simmons
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.