Simple WAMP (WebSocket Application Messaging Protocol) Javascript client-side implementation

• Description
• Usage example
• Quick comparison to other libs
• Installation
• Methods
  • Constructor
  • options
  • getOpStatus
  • getSessionId
  • connect
  • disconnect
  • abort
  • subscribe
  • unsubscribe
  • publish
  • call
  • register
  • unregister
• 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.

Back to TOC

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!');

Back to TOC

Which one library to use - choice is yours!

Back to TOC

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>

Back to TOC

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 });

Back to TOC

.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...'); }
});

Back to TOC

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!" }

Back to TOC

Returns the WAMP Session ID.

ws.getSessionId();

Back to TOC

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');

Back to TOC

Disconnects from wamp server. Clears all queues, subscription, calls. Supports chaining.

ws.disconnect();

Back to TOC

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();

Back to TOC

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'); }
});

Back to TOC

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');

Back to TOC

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 });

Back to TOC

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);
	}
});

Back to TOC

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);
	}
});

Back to TOC

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);
	}
});

Back to TOC

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.

Back to TOC

• WAMP specification
• Wiola - WAMP in Lua on top of nginx/openresty

Back to TOC