Feature-rich, lightweight and zero dependency (by default) WAMP (WebSocket Application Messaging Protocol) Javascript implementation (for browser and node.js)
Wampy.js is javascript library, that runs both in browser and node.js environments, and even in react native environment. It implements WAMP v2 specification on top of WebSocket object, also provides additional features like auto-reconnecting. It has no external dependencies (by default) and is easy to use. Also, it provides (starting from v7.1) command line wamp client which can be extremely helpful in quick check/debug existing WAMP-based APIs.
Wampy.js supports the following WAMP roles and features:
Wampy supports the following serializers:
In node.js environment Wampy is compatible with the following websocket clients:
For convenience, all API documentation is also available as a GitBook here.
const wampy = new Wampy('/ws/', { realm: 'AppRealm' });
try {
await wampy.connect();
} catch (e) {
console.log('connection failed', e);
}
try {
await wampy.subscribe('system.monitor.update', (eventData) => {
console.log('Received event:', eventData);
});
} catch (e) {
console.log('subscription failed', e);
}
try {
const res = await wampy.call('get.server.time');
console.log('RPC called. Server time:', res.argsDict.serverTime);
} catch (e) {
console.log('RPC call failed', e);
}
// Somewhere else for example
await wampy.publish('system.monitor.update');
// or just ignore promise if you don't need it
wampy.publish('client.message', 'Hi guys!');
Wampy.js can be installed using npm:
npm install -S wampy
For browser usage download the latest browser.zip archive and add wampy-all.min.js file to your page. It contains msgpack encoder plus wampy itself.
<script src="browser/wampy-all.min.js"></script>
If you don't plan to use msgpack, just include wampy.min.js.
<script src="browser/wampy.min.js"></script>
In case you are using build tools or bundlers like grunt/gulp/webpack/rollup/vite/etc, your entry point can be * src/wampy.js* if you transpile you code, or dist/wampy.js (default package entry point) which is already transpiled to "env" preset, which means it works out of the box, just bundle modules.
Wampy cli tool exposes almost the same API options to the command line interface. You can use all types of authorization, publish, subscribe, register and call any URI. Some WAMP Actions provides additional helper options (e.g. mirror
option in register command that allows to return back the invocation payload to the caller).
Cli tool is charged with rich help descriptions, examples and even shell auto-completion script. All parameters may be passed as cmd args or via related ENV Vars for convenience. So you can for example export WAMP Router URI and realm to the environment and provide only wamp action parameters via cmd.
You can install wampy cli tool globally or call it by npx:
npm install -g wampy
# After this you can invoke wampy
wampy -h
# or just run wampy with npx
npx wampy -h
Check the wampy -h
or wampy --help
for the available commands and global options and check the help for a specific command by issuing wampy <call|register|publish|subscribe> -h
.
To make use of shell auto-completion features just add output of wampy completion
to your shell config:
wampy completion > ~/.zshrc
# or
wampy completion > ~/.bashrc
The completion
command is hidden from the wampy -h
output to not pollute the main use flow as it is only needed once.
Please refer to Migrating.md for instructions on upgrading major versions.
Below is a description of the exposed public API. Wampy also has type definitions available at DefinitelyTyped.org, but they are only for versions < 7.x for now. Feel free to update!)
Wampy constructor can take 2 parameters:
realm
. For node.js environment it's also necessary to specify ws
- websocket module. See description below.// in browser
wampy = new Wampy();
wampy = new Wampy('/my-socket-path');
wampy = new Wampy('wss://socket.server.com:5000/ws', { autoReconnect: false });
wampy = new Wampy({ reconnectInterval: 1*1000 });
// in node.js
w3cws = require('websocket').w3cwebsocket;
wampy = new Wampy(null, { ws: w3cws });
wampy = new Wampy('/my-socket-path', { ws: w3cws });
wampy = new Wampy('wss://socket.server.com:5000/ws', { autoReconnect: false, ws: w3cws });
wampy = new Wampy({ reconnectInterval: 1*1000, ws: w3cws });
// or using ws example
import WebSocket from 'ws';
wampy = new Wampy(null, { ws: WebSocket });
wampy = new Wampy('/my-socket-path', { ws: WebSocket });
wampy = new Wampy('wss://socket.server.com:5000/ws', { autoReconnect: false, ws: WebSocket });
wampy = new Wampy({ reconnectInterval: 1*1000, ws: WebSocket });
Json serializer will be used by default. If you want to use msgpack or cbor serializer, pass it through options. Also, you can use your own serializer if it is supported on the WAMP router side.
// in browser
wampy = new Wampy('wss://socket.server.com:5000/ws', {
serializer: new MsgpackSerializer()
});
wampy = new Wampy({
serializer: new CborSerializer()
});
// in node.js
import { Wampy } from 'wampy';
import { MsgpackSerializer } from 'wampy/MsgpackSerializer';
import { CborSerializer } from 'wampy/CborSerializer';
import WebSocket from 'ws';
wampy = new Wampy('wss://socket.server.com:5000/ws', {
ws: WebSocket,
serializer: new MsgpackSerializer()
});
wampy = new Wampy({
ws: w3cws,
serializer: new CborSerializer()
});
.options() method is now deprecated, so this is here only for documentation purposes. Please use getOptions()/setOptions()
instead.
.options() can be called in two forms: -- without parameters it will behave the same as new method getOptions() -- with one parameter as a hash-table it will behave the same as new method setOptions()
wampy.options(); // same as wampy.getOptions
wampy.options({ // same as wampy.setOptions
authPlugins: {
ticket: ((userPassword) => (() => userPassword ))(),
wampcra: wampyCra.sign(secret),
cryptosign: wampyCryptosign.sign(privateKey)
},
authMode: 'auto'
});
Returns Wampy configuration options. See setOptions() down below for the full list of available options.
wampy.getOptions();
Receives a newOptions object as a parameter, where each property is a new option to be set and returns a Wampy instance.
Options attributes description:
debug=true
and no logger
specified, console.log
will be used.loose
for less strict URI validation.const wampyCra = require('wampy-cra');
const wampyCryptosign = require('wampy-cryptosign');
wampy.setOptions({
authPlugins: {
// No need to process challenge data in ticket flow, as it is empty
ticket: ((userPassword) => (() => userPassword ))(),
wampcra: wampyCra.sign(secret),
cryptosign: wampyCryptosign.sign(privateKey)
},
authMode: 'auto'
});
manual
. Possible values: manual
|auto
. Mode of authorization flow. If it is set to manual
- you also need to provide onChallenge callback, which will process authorization challenge. Or you can set it to auto
and provide authPlugins (described above). In this case the necessary authorization flow will be chosen automatically. This allows to support few authorization methods simultaneously.json
.{ json: jsonSerializer }
. User provided hashmap of serializer instances for using in Payload Passthru Mode. Allows to specify a few serializers and use them on per message/call basis.wampy.setOptions({
reconnectInterval: 1000,
maxRetries: 999,
onClose: () => { console.log('See you next time!'); },
onError: () => { console.log('Breakdown happened'); },
onReconnect: () => { console.log('Reconnecting...'); },
onReconnectSuccess: (welcomeDetails) => { console.log('Reconnection succeeded. Details:', welcomeDetails); }
});
Returns the status of last operation. This method returns an object with attributes:
code
is integer, and value > 0 means error.error
is Error instance of last operation. Check errors types exposed by wampy.reqId
is a Request ID of last successful operation. It is useful in some cases (call canceling for example).const defer = ws.publish('system.monitor.update');
console.log(ws.getOpStatus());
// may return
// { code: 1, error: UriError instance }
// or { code: 2, error: NoBrokerError instance }
// or { code: 0, error: null }
Returns the WAMP Session ID.
ws.getSessionId();
Connects to wamp server. url parameter is the same as specified in Constructor. Returns a Promise
that's either:
try {
await wampy.connect();
} catch (e) {
console.log('connection failed', e);
}
await ws.connect('/my-socket-path');
const defer = ws.connect('wss://socket.server.com:5000/ws');
Disconnects from wamp server. Clears all queues, subscription, calls. Returns a Promise
that's either:
await ws.disconnect();
Aborts WAMP session and closes a websocket connection. If it is called on handshake stage - it sends the abort
message to wamp server (as described in spec). Also clears all queues, subscription, calls. Returns wampy instance back.
ws.abort();
With Ticket-based authentication, the client needs to present the server an authentication "ticket" - some magic value to authenticate itself to the server. It could be a user password, an authentication token or any other kind of client secret. To use it you need to provide "ticket" in "authmethods", "authid" and the "onChallenge" callback as wampy instance options.
'use strict';
// Ticket authentication
wampy = new Wampy('wss://wamp.router.url', {
realm: 'realm1',
authid: 'joe',
authmethods: ['ticket'],
onChallenge: (method, info) => {
console.log('Requested challenge with ', method, info);
return 'joe secret key or password';
}
});
// Promise-based ticket authentication
wampy = new Wampy('wss://wamp.router.url', {
realm: 'realm1',
authid: 'micky',
authmethods: ['ticket'],
onChallenge: (method, info) => {
return new Promise((resolve, reject) => {
setTimeout(() => {
console.log('Requested challenge with ', method, info);
resolve('micky secret key or password');
}, 2000);
});
}
});
Wampy.js supports challenge response authentication. To use it you need to provide the "authid" and the "onChallenge" callback as wampy instance options. Also, Wampy.js supports wampcra
authentication method with a little helper plugin "wampy-cra". Just add "wampy-cra" package and use provided methods as shown below.
'use strict';
const Wampy = require('wampy').Wampy;
const wampyCra = require('wampy-cra');
const w3cws = require('websocket').w3cwebsocket;
// Manual authentication using signed message
wampy = new Wampy('wss://wamp.router.url', {
ws: w3cws, // just for example in node.js env
realm: 'realm1',
authid: 'joe',
authmethods: ['wampcra'],
onChallenge: (method, info) => {
console.log('Requested challenge with ', method, info);
return wampyCra.signManual('joe secret key or password', info.challenge);
}
});
// Promise-based manual authentication using signed message
wampy = new Wampy('wss://wamp.router.url', {
realm: 'realm1',
authid: 'micky',
authmethods: ['wampcra'],
onChallenge: (method, info) => {
return new Promise((resolve, reject) => {
setTimeout(() => {
console.log('Requested challenge with ', method, info);
resolve(wampyCra.signManual('micky secret key or password', info.challenge));
}, 2000);
});
}
});
// Manual authentication using salted key and pbkdf2 scheme
wampy = new Wampy('wss://wamp.router.url', {
realm: 'realm1',
authid: 'peter',
authmethods: ['wampcra'],
onChallenge: (method, info) => {
const iterations = 100;
const keylen = 16;
const salt = 'password salt for user peter';
console.log('Requested challenge with ', method, info);
return wampyCra.signManual(wampyCra.deriveKey('peter secret key or password', salt, iterations, keylen), info.challenge);
}
});
// Automatic CRA authentication
wampy = new Wampy('wss://wamp.router.url', {
realm: 'realm1',
authid: 'patrik',
authmethods: ['wampcra'],
onChallenge: wampyCra.sign('patrik secret key or password')
});
Wampy.js supports cryptosign-based authentication. To use it you need to provide authid
, onChallenge
callback and authextra
as wampy instance options. Also, Wampy.js supports cryptosign
authentication method with a little helper plugin "wampy-cryptosign". Just add "wampy-cryptosign" package and use provided methods as shown below.
The authextra
option may contain the following properties for WAMP-Cryptosign:
Field | Type | Required | Description |
---|---|---|---|
pubkey | string | yes | The client public key (32 bytes) as a Hex encoded string, e.g. 545efb0a2192db8d43f118e9bf9aee081466e1ef36c708b96ee6f62dddad9122 |
channel_binding* | string | no | If TLS channel binding is in use, the TLS channel binding type, e.g. "tls-unique" . |
challenge | string | no | A client chosen, random challenge (32 bytes) as a Hex encoded string, to be signed by the router. |
trustroot | string | no | When the client includes a client certificate, the Ethereum address of the trustroot of the certificate chain to be used, e.g. 0x72b3486d38E9f49215b487CeAaDF27D6acf22115 , which can be a Standalone Trustroot or an On-chain Trustroot |
*: channel_binding
is not supported yet. And may be supported only in node.js environment.
'use strict';
import { Wampy } from 'wampy';
import * as wampyCS from 'wampy-cryptosign';
// or you can import only the "sign" method
// import { sign } from 'wampy-cryptosign';
// Manual authentication using signed message
wampy = new Wampy('wss://wamp.router.url', {
realm: 'realm1',
authid: 'joe',
authmethods: ['cryptosign'],
authextra: {
pubkey: '545efb0a2192db8d43f118e9bf9aee081466e1ef36c708b96ee6f62dddad9122'
},
onChallenge: (method, info) => {
console.log('Requested challenge with ', method, info);
return wampyCS.sign('joe secret (private) key')(method, info);
}
});
// Promise-based manual authentication using signed message
wampy = new Wampy('wss://wamp.router.url', {
realm: 'realm1',
authid: 'micky',
authmethods: ['cryptosign'],
authextra: {
pubkey: '545efb0a2192db8d43f118e9bf9aee081466e1ef36c708b96ee6f62dddad9122'
},
onChallenge: (method, info) => {
return new Promise((resolve, reject) => {
setTimeout(() => {
console.log('Requested challenge with ', method, info);
resolve(wampyCS.sign('micky secret (private) key')(method, info));
}, 2000);
});
}
});
// Automatic CryptoSign authentication
wampy = new Wampy('wss://wamp.router.url', {
realm: 'realm1',
authid: 'patrik',
authmethods: ['cryptosign'],
authextra: {
pubkey: '545efb0a2192db8d43f118e9bf9aee081466e1ef36c708b96ee6f62dddad9122'
},
onChallenge: wampyCS.sign('patrik secret (private) key')
});
If you server provides multiple options for authorization, you can configure wampy.js to automatically choose required authorization flow based on authmethod
requested by server. For this flow you need to configure the following options:
authid
. Authentication id to use in challengeauthmethods
. Supported authentication methodsauthextra
. Additional authentication optionsauthPlugins
. Authentication helpers for processing different authmethods challenge flowsauthMode
. Mode of authorization flow. Should be set to auto
onChallenge
. onChallenge callback. Is not used when authMode=auto
import { Wampy } from 'wampy';
import * as wampyCra from 'wampy-cra';
import * as wampyCS from 'wampy-cryptosign';
wampy = new Wampy('wss://wamp.router.url', {
realm: 'realm1',
authid: 'patrik',
authmethods: ['ticket', 'wampcra', 'cryptosign'],
authextra: { // User public key for Cryptosign-based Authentication
pubkey: '545efb0a2192db8d43f118e9bf9aee081466e1ef36c708b96ee6f62dddad9122'
},
authPlugins: {
ticket: ((userPassword) => (() => userPassword ))(),
wampcra: wampyCra.sign(userSecret),
cryptosign: wampyCS.sign(userPrivateKey)
},
authMode: 'auto',
onChallenge: null
});
Subscribes for topicURI events.
Input Parameters:
Returns a Promise
that's either:
await ws.subscribe('chat.message.received', (eventData) => { console.log('Received new chat message!', eventData); });
try {
const res = await ws.subscribe('some.another.topic',
(eventData) => {
console.log('Received topic event', eventData);
}
);
console.log('Successfully subscribed to topic: ' + res.topic);
} catch (e) {
console.log('Subscription error:' + e.error);
}
Unsubscribe subscription from receiving events.
Parameters:
Returns a Promise
that's either:
const f1 = (data) => { console.log('this was event handler for topic') };
await ws.unsubscribe('subscribed.topic', f1);
const defer = ws.unsubscribe('chat.message.received');
Publish a new event to topic.
Parameters:
Returns a Promise
that's either:
await ws.publish('user.logged.in');
await ws.publish('chat.message.received', 'user message'); // will be sent as ['user message1']
await ws.publish('chat.message.received', ['user message1', 'user message2']);
await ws.publish('user.modified', { field1: 'field1', field2: true, field3: 123 });
await ws.publish('chat.message.received', ['Private message'], { eligible: 123456789 });
try {
await ws.publish('user.modified', { field1: 'field1', field2: true, field3: 123 });
console.log('User successfully modified');
} catch (e) {
console.log('User modification failed', e.error, e.details);
}
Make an RPC call to topicURI.
Parameters:
Returns a Promise
that's either:
Important note on progressive call results:
For getting a progressive call results you need to specify progress_callback
in advancedOptions
. This callback will be fired on every intermediate result. But the last one result or error will be processed on promise returned from the .call()
. That means that final call result will be received by call promise resolve
handler.
const result = await ws.call('server.time');
console.log('Server time is ' + result.argsList[0]);
try {
await ws.call('start.migration');
console.log('RPC successfully called');
} catch (e) {
console.log('RPC call failed!', e.error);
}
try {
await ws.call('restore.backup', { backupFile: 'backup.zip' });
console.log('Backup successfully restored');
} catch (e) {
console.log('Restore failed!', e.error, e.details);
}
RPC invocation cancelling.
Parameters:
Returns a Boolean
or throws an Error
:
true
if successfully sent canceling messageError
if some error occurredconst defer = ws.call('start.migration');
defer
.then((result) => console.log('RPC successfully called'))
.catch((e) => console.log('RPC call failed!', e));
status = ws.getOpStatus();
ws.cancel(status.reqId);
RPC registration for invocation.
Parameters:
Returns a Promise
that's either:
Registered PRC during invocation will receive one hash-table argument with following attributes:
{ progress: true }
for intermediate results.RPC can return no result (undefined), any single value, array or hash-table object:
"progress": true
, which indicates, that it's a progressive result, so there will be more results in the future. Be sure to unset "progress" on last result message.const sqrt_f = function (data) { return { result: data.argsList[0]*data.argsList[0] } };
await ws.register('sqrt.value', sqrt_f);
try {
await ws.register('sqrt.value', sqrt_f);
console.log('RPC successfully registered');
} catch (e) {
console.log('RPC registration failed!', e);
}
Also, wampy supports rpc with asynchronous code, such as some user interactions or xhr, using promises. For using this functionality in old browsers you should use polyfills, like es6-promise. Check browser support at can i use site.
const getUserName = () => {
return new Promise((resolve, reject) => {
/* Ask user to input his username somehow,
and resolve promise with user input at the end */
resolve({ argsList: userInput });
});
};
ws.register('get.user.name', getUserName);
Also, it is possible to abort rpc processing and throw error with custom application specific data. This data will be passed to caller onError callback.
Exception object with custom data may have the following attributes:
Note: Any other type of errors (like built in Javascript runtime TypeErrors, ReferenceErrors) and exceptions are caught by wampy and sent back to the client's side, not just this type of custom errors. In this case the details of the error can be lost.
const getSystemInfo = () => {
// Application logic
// for example, if you need to get data from db
// and at this time you can't connect to db
// you can throw exception with some details for client application
const UserException = () => {
this.error = 'app.error.no_database_connection';
this.details = {
errorCode: 'ECONNREFUSED',
errorMessage: 'Connection refused by a remote host.',
database: 'db',
host: '1.2.3.4',
port: 5432,
dbtype: 'postgres'
};
this.argsList = ['Not able to connect to the database.'];
this.argsDict = {};
};
throw new UserException();
};
await wampy.register('get.system.info', getSystemInfo);
try {
await wampy.call('get.system.info');
} catch (error) {
console.log('Error happened', error);
}
RPC unregistration from invocations.
Parameters:
Returns a Promise
that's either:
await ws.unregister('sqrt.value');
try {
ws.unregister('sqrt.value');
console.log('RPC successfully unregistered');
} catch (e) {
console.log('RPC unregistration failed!', e);
}
During wampy instance lifetime there can be many cases when error happens: some made by developer mistake, some are bound to WAMP protocol violation, some came from other peers. Errors that can be caught by wampy instance itself are stored in opStatus.error
, while others are just thrown.
This allows, for example, convenient handling of different types of errors:
import {Wampy, Errors} from 'wampy';
const wampy = new Wampy('/ws/', { realm: 'AppRealm' });
try {
await wampy.call('start.migration');
console.log('RPC successfully called');
} catch (error) {
console.log('Error happened!');
if (error instanceof Errors.UriError) {
// statements to handle UriError exceptions
} else if (error instanceof Errors.InvalidParamError) {
// statements to handle InvalidParamError exceptions
} else if (error instanceof Errors.NoSerializerAvailableError) {
// statements to handle NoSerializerAvailableError exceptions
} else {
// statements to handle any unspecified exceptions
}
}
Wampy package exposes the following Error
classes:
For errors attributes look at src/errors.js file.
From v5.0 version there is option to provide custom serializer.
Custom serializer instance must meet a few requirements:
encode (data)
method, that returns encoded datadecode (data)
method, that returns decoded dataprotocol
string property, that contains a protocol name. This name is concatenated with "wamp.2." string and is then passed as websocket subprotocol http header.isBinary
boolean property, that indicates, is this a binary protocol or not.Take a look at JsonSerializer.js or MsgpackSerializer.js as examples.
Starting from v6.2.0 version you can pass additional HTTP Headers and TLS parameters to underlying socket connection in node.js environment (thnx websocket
library). See example below. For wsRequestOptions
you can pass any option, described in tls.connect options documentation.
const Wampy = require('wampy').Wampy;
const w3cws = require('websocket').w3cwebsocket;
wampy = new Wampy('wss://wamp.router.url:8888/wamp-router', {
ws: w3cws,
realm: 'realm1',
additionalHeaders: {
'X-ACL-custom-token': 'dkfjhsdkjfhdkjs',
'X-another-custom-header': 'header-value'
},
wsRequestOptions: {
ca: fs.readFileSync('ca-crt.pem'),
key: fs.readFileSync('client1-key.pem'),
cert: fs.readFileSync('client1-crt.pem'),
host: 'wamp.router.url',
port: 8888,
rejectUnauthorized: false, // this setting allow to connect to untrusted (or self signed) TLS certificate,
checkServerIdentity: (servername, cert) => {
// A callback function to be used (instead of the builtin tls.checkServerIdentity() function)
// when checking the server's hostname (or the provided servername when explicitly set)
// against the certificate. This should return an <Error> if verification fails.
// The method should return undefined if the servername and cert are verified.
if (servername !== 'MyTrustedServerName') {
return new Error('Bad server!');
}
}
}
});
Wampy.js uses mocha and chai for tests and c8/istanbul for code coverage. Wampy sources are mostly all covered with tests! :)
# use standard npm test command
> npm test
# or only some tests
> npm run test:node
> npm run test:node-no-crossbar
> npm run test:browser
# for code coverage report run
> npm run cover
# and then open coverage/lcov-report/index.html
Thanks JetBrains for support! Best IDEs for every language!
Author: KSDaemon
Source Code: https://github.com/KSDaemon/wampy.js
License: MIT license