/wampy.js

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

Primary LanguageJavaScriptMIT LicenseMIT

wampy.js

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

NPM version Build Status Dependency Status DevDependency Status MIT License

Gitter Chat

Table of Contents

Description

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.
    • progressive call results.
  • 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

Usage example

var ws = new Wampy('/ws/', { realm: 'AppRealm' });
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

Quick comparison to other libs

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!

Back to TOC

Installation

Wampy.js can be installed using bower or npm or just by file-copy :)

> bower install wampy.js
# Or
> npm install wampy

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

Methods

Constructor([url[, options]])

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. The only required field is realm. See description below.
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([opts])

.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: undefined. 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

getOpStatus()

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 or 3 attributes: code and description and possible request ID . Code is integer, and value > 0 means error. Description is a description of code. Request ID is integer and may be useful in some cases (call canceling for example).

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!" }
// or { code: 0, description: "Success!", reqId: 1565723572 }

Back to TOC

getSessionId()

Returns the WAMP Session ID.

ws.getSessionId();

Back to TOC

connect([url])

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

disconnect()

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

ws.disconnect();

Back to TOC

abort()

Aborts WAMP session and closes a websocket connection. Supports chaining. 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

subscribe(topicURI, callbacks)

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(topicURI[, callbacks])

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(topicURI[, payload[, callbacks[, advancedOptions]]])

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

call(topicURI[, payload[, callbacks[, advancedOptions]]])

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
       receive_progress: bool flag for receiving progressive results. In this case onSuccess function
                  will be called every time on receiving result }

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

cancel(reqId, callbacks, advancedOptions)

RPC invocation cancelling. Supports chaining.

Parameters:

  • reqId. Required. Request ID of RPC call that need to be canceled.

  • callbacks. Optional. If it is a function - it will be called if successfully sent canceling message or it can be hash table of callbacks:

        { onSuccess: will be called if successfully sent canceling message
      onError: will be called if some error occurred }

  • advancedOptions. Optional parameter. Must include any or all of the options:

        { mode: string|one of the possible modes:
            "skip" | "kill" | "killnowait". Skip is default. }

ws.call('start.migration', null, {
	onSuccess: function (data) {
		console.log('RPC successfully called');
	},
	onError: function (err) {
		console.log('RPC call failed!',err);
	}
});
status = ws.getOpStatus();

ws.cancel(status.reqId);

register(topicURI, callbacks)

RPC registration for invocation. Supports chaining.

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

unregister(topicURI, callbacks)

RPC unregistration from invocations. Supports chaining.

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

Copyright and License

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

See Also

Back to TOC