Simple WAMP (WebSocket Application Messaging Protocol) Javascript client-side implementation
- Description
- Usage example
- Quick comparison to other libs
- Installation
- Methods
- Copyright and License
- See Also
Wampy.js is client-side javascript library. It implements WAMP v2 specification on top of WebSocket object, also provides additional features like autoreconnecting and use of Chaining Pattern. It has no external dependencies (by default) and is easy to use. Also it's compatible with AMD and browserify.
Wampy.js supports next WAMP roles and features:
- publisher: advanced profile with features:
- subscriber blackwhite listing
- publisher exclusion
- publisher identification
- subscriber: basic profile.
- caller: advanced profile with features:
- callee blackwhite listing.
- caller exclusion.
- caller identification.
- callee: basic profile.
Wampy default serializer is JSON, but it also supports msgpack as serializer, but you need to include msgpack.js as dependency.
For v1 WAMP implementation, please see tag v0.1.0.
var ws = new Wampy('/ws/');
ws.subscribe('system.monitor.update', function (data) { console.log('Received system.monitor.update event!'); })
.subscribe('client.message', function (data) { console.log('Received client.message event!'); })
ws.call('get.server.time', null, {
onSuccess: function (stime) {
console.log('RPC successfully called');
console.log('Server time is ' + stime);
},
onError: function (err) {
console.log('RPC call failed with error ' + err);
}
});
// Somewhere else for example
ws.publish('system.monitor.update');
ws.publish('client.message', 'Hi guys!');
Topic | Wampy.js | AutobahnJS |
---|---|---|
Runs on | browser | browser and NodeJS |
Dependencies | msgpack.js (optional), jDataView (optional) | when.js, CryptoJS (optional) |
Creating connection | var connection = new Wampy('ws://127.0.0.1:9000/', { realm: 'realm1' }); | var connection = new autobahn.Connection({url: 'ws://127.0.0.1:9000/', realm: 'realm1'}); |
Opening a connection | connection opens on creating an instance, or can be opened by: connection.connect() | connection.open(); |
Connection Callbacks | Wampy supports next callbacks: onConnect, onClose, onError, onReconnect. Callbacks can be specified via options object passed to constructor, or via .options() method. | AutobahnJS provides two callbacks: connection.onopen = function (session) { } and connection.onclose = function (reason/string, details/dict) { } |
WAMP API methods with parameters | While using Wampy you don't have to explicitly specify the payload type (single value, array, object), just pass it to api method. For example: ws.publish('chat.message.received', 'user message'); ws.publish('chat.message.received', ['user message1', 'user message2']); ws.publish('chat.message.received', { message: 'user message'}); Also Wampy is clever enough to understand some specific options, for example, if you specify a success or error callback to publish method, Wampy will automatically set acknowledge flag to true. |
In AutobahnJS you need to use only arrays and objects, as it's specified in WAMP, and also choose right argument position. For example: session.publish('com.myapp.hello', ['Hello, world!']); session.publish('com.myapp.hello', [], {message: 'Hello, world!'}); Also you need to explicitly provide additional options, like {acknowledge: true} |
Method callbacks | Most of the API methods take a callbacks parameter, which is hash-table of posible callbacks | AutobahnJS make use of Deffered object, and most of API methods return a deferred object, so you can specify callbacks using .then() method |
Chaining support | Wampy supports methods chaining. connection.subscribe(...).publish(...).call(...) |
Which one library to use - choice is yours!
To use Wampy simply add wampy-all.min.js file to your page. It contains all the necessary libs: jdataview - for handling UInt64 data and msgpack encoder.
<script src="wampy-all.min.js"></script>
In case, you don't plan to use msgpack, just include clean wampy.min.js.
<script src="wampy.min.js"></script>
Wampy constructor can take 2 parameters:
- url to wamp server - optional. If its undefined, page-schema://page-server:page-port/ws will be used.
Can be in forms of:
- fully qualified url: schema://server:port/path
- server:port/path. In this case page schema will be used.
- /path. In this case page schema, server, port will be used.
- options hash-table - optional. See description.
ws = new Wampy();
ws = new Wampy('/my-socket-path');
ws = new Wampy('ws://socket.server.com:5000/ws', { autoReconnect: false });
ws = new Wampy({ reconnectInterval: 1*1000 });
.options() method can be called in two forms:
- without parameters it will return current options
- with one parameter as hash-table it will set new options. Support chaining.
Options attributes description:
- autoReconnect. Default value: true. Enable autoreconnecting. In case of connection failure, Wampy will try to reconnect to WAMP server, and if you were subscribed to any topics, or had registered some procedures, Wampy will resubscribe to that topics and reregister procedures.
- reconnectInterval. Default value: 2000 (ms). Reconnection Interval in ms.
- maxRetries. Default value: 25. Max reconnection attempts. After reaching this value .disconnect() will be called
- transportEncoding. Default value: json. Transport serializer to use. Supported 2 values: json|msgpack. For using msgpack you need to include msgpack javascript library, and also wamp server, that also supports it.
- realm. Default value: window.location.hostname. WAMP Realm to join on server. See WAMP spec for additional info.
- onConnect. Default value: undefined. Callback function. Fired when connection to wamp server is established.
- onClose. Default value: undefined. Callback function. Fired on closing connection to wamp server.
- onError. Default value: undefined. Callback function. Fired on error in websocket communication.
- onReconnect. Default value: undefined. Callback function. Fired every time on reconnection attempt.
ws.options();
ws.options({
reconnectInterval: 1000,
maxRetries: 999,
onConnect: function () { console.log('Yahoo! We are online!'); },
onClose: function () { console.log('See you next time!'); },
onError: function () { console.log('Breakdown happened'); },
onReconnect: function () { console.log('Reconnecting...'); }
});
Returns the status of last operation. Wampy is developed in a such way, that every operation returns this even in case of error to suport chaining. But if you want to know status of last operation, you can call .getOpStatus(). This method returns an object with 2 attributes: code and description. Code is integer, and value > 0 means error. Description is a description of code.
ws.publish('system.monitor.update');
ws.getOpStatus();
// may return { code: 1, description: "Topic URI doesn't meet requirements!" }
// or { code: 2, description: "Server doesn't provide broker role!" }
Returns the WAMP Session ID.
ws.getSessionId();
Connects to wamp server. url parameter is the same as specified in Constructor. Supports chaining.
ws.connect();
ws.connect('/my-socket-path');
ws.connect('wss://socket.server.com:5000/ws');
Disconnects from wamp server. Clears all queues, subscription, calls. Supports chaining.
ws.disconnect();
Aborts WAMP session and closes a websocket connection. If it is called on handshake stage - it sends a abort message to wamp server (as described in spec). Also clears all queues, subscription, calls. Supports chaining.
ws.abort();
Subscribes for topicURI events. Supports chaining.
Parameters:
-
topicURI. Required. A string that identifies the topic. Must meet a WAMP Spec URI requirements.
-
callbacks. If it is a function - it will be treated as published event callback or it can be hash table of callbacks:
{ onSuccess: will be called when subscribe would be confirmed onError: will be called if subscribe would be aborted onEvent: will be called on receiving published event }
ws.subscribe('chat.message.received', function (msg) { console.log('Received new chat message!'); });
ws.subscribe('some.another.topic', {
onSuccess: function () { console.log('Successfully subscribed to topic'); },
onError: function (err) { console.log('Subscription error:' + err); },
onEvent: function (data) { console.log('Received topic event'); }
});
Unsubscribe from topicURI events. Supports chaining.
Parameters:
-
topicURI. Required. A string that identifies the topic. Must meet a WAMP Spec URI requirements.
-
callbacks. If it is a function - it will be treated as published event callback to remove or it can be hash table of callbacks:
{ onSuccess: will be called when unsubscribe would be confirmed onError: will be called if unsubscribe would be aborted onEvent: published event callback to remove }
or it can be not specified, in this case all callbacks and subscription will be removed.
var f1 = function (data) { ... };
ws.unsubscribe('subscribed.topic', f1);
ws.unsubscribe('chat.message.received');
Publish a new event to topic. Supports chaining.
Parameters:
-
topicURI. Required. A string that identifies the topic. Must meet a WAMP Spec URI requirements.
-
payload. Publishing event data. Optional. May be any single value or array or hash-table object or null.
-
callbacks. Optional hash table of callbacks:
{ onSuccess: will be called when publishing would be confirmed onError: will be called if publishing would be aborted }
-
advancedOptions. Optional parameter. Must include any or all of the options:
{ exclude: integer|array WAMP session id(s) that won't receive a published event, even though they may be subscribed eligible: integer|array WAMP session id(s) that are allowed to receive a published event exclude_me: bool flag of receiving publishing event by initiator (if it is subscribed to this topic) disclose_me: bool flag of disclosure of publisher identity (its WAMP session ID) to receivers of a published event }
ws.publish('user.logged.in');
ws.publish('chat.message.received', 'user message');
ws.publish('chat.message.received', ['user message1', 'user message2']);
ws.publish('user.modified', { field1: 'field1', field2: true, field3: 123 });
ws.publish('user.modified', { field1: 'field1', field2: true, field3: 123 }, {
onSuccess: function () { console.log('User successfully modified'); }
});
ws.publish('user.modified', { field1: 'field1', field2: true, field3: 123 }, {
onSuccess: function () { console.log('User successfully modified'); },
onError: function (err) { console.log('User modification failed', err); }
});
ws.publish('chat.message.received', ['Private message'], null, { eligible: 123456789 });
Make a RPC call to topicURI. Supports chaining.
Parameters:
-
topicURI. Required. A string that identifies the remote procedure to be called. Must meet a WAMP Spec URI requirements.
-
payload. RPC data. Optional. May be any single value or array or hash-table object or null.
-
callbacks. If it is a function - it will be treated as result callback function or it can be hash table of callbacks:
{ onSuccess: will be called with result on successful call onError: will be called if invocation would be aborted }
-
advancedOptions. Optional parameter. Must include any or all of the options:
{ exclude: integer|array WAMP session id(s) providing an explicit list of (potential) Callees that a call won't be forwarded to, even though they might be registered eligible: integer|array WAMP session id(s) providing an explicit list of (potential) Callees that are (potentially) forwarded the call issued exclude_me: bool flag of potentially forwarding call to caller if he is registered as callee disclose_me: bool flag of disclosure of Caller identity (WAMP session ID) to endpoints of a routed call }
ws.call('server.time', null, function (data) { console.log('Server time is ' + d[0]); });
ws.call('start.migration', null, {
onSuccess: function (data) {
console.log('RPC successfully called');
},
onError: function (err) {
console.log('RPC call failed!',err);
}
});
ws.call('restore.backup', { backupFile: 'backup.zip' }, {
onSuccess: function (data) {
console.log('Backup successfully restored');
},
onError: function (err) {
console.log('Restore failed!',err);
}
});
RPC registration for invocation.
Parameters:
-
topicURI. Required. A string that identifies the remote procedure to be called. Must meet a WAMP Spec URI requirements.
-
callbacks. Required. If it is a function - it will be treated as rpc itself or it can be hash table of callbacks:
{ rpc: registered procedure onSuccess: will be called on successful registration onError: will be called if registration would be aborted }
var sqrt_f = function (x) { return x*x; };
ws.register('sqrt.value', sqrt_f);
ws.register('sqrt.value', {
rpc: sqrt_f,
onSuccess: function (data) {
console.log('RPC successfully registered');
},
onError: function (err) {
console.log('RPC registration failed!',err);
}
});
RPC unregistration from invocations
Parameters:
-
topicURI. Required. A string that identifies the remote procedure to be called. Must meet a WAMP Spec URI requirements.
-
callbacks. Optional. If it is a function - it will be called on successful unregistration or it can be hash table of callbacks:
{ onSuccess: will be called on successful unregistration onError: will be called if unregistration would be aborted }
ws.unregister('sqrt.value');
ws.unregister('sqrt.value', {
onSuccess: function (data) {
console.log('RPC successfully unregistered');
},
onError: function (err) {
console.log('RPC unregistration failed!',err);
}
});
Wampy.js library is licensed under the MIT License (MIT).
Copyright (c) 2014 Konstantin Burkalev
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.
- WAMP specification
- Wiola - WAMP in Lua on top of nginx/openresty