Wampy.js

About

Amazingly fast, feature-rich, lightweight and zero dependency (by default) WAMP (Web Application Messaging Protocol) client for browser and node.js, written in TypeScript

[![NPM version][npm-image]][npm-url] [![Build Status][gh-build-test-image]][gh-build-test-url] [![Code coverage][coveralls-image]][coveralls-url] [![MIT License][license-image]][license-url] [![Known Vulnerabilities][snyk-image]][snyk-url]

Table of Contents

<!-- TOC -->

• Wampy.js
  • About
  • Table of Contents
  • Description
  • Usage example
  • Installation
  • Exported components
  • CLI tool
  • Migrating or Updating versions
  • API
    • Constructor([url[, options]])
    • getOptions()
    • setOptions([newOptions])
    • getOpStatus()
    • getSessionId()
    • connect([url])
    • disconnect()
    • abort()
    • Ticket-based Authentication
    • Challenge Response Authentication
    • Cryptosign-based Authentication
    • Automatically chosen Authentication
    • subscribe(topicURI, onEvent[, advancedOptions])
    • unsubscribe(subscriptionIdKey[, onEvent])
    • publish(topicURI[, payload[, advancedOptions]])
    • call(topicURI[, payload[, advancedOptions]])
    • progressiveCall(topicURI[, payload[, advancedOptions]])
    • cancel(reqId[, advancedOptions])
    • register(topicURI, rpc[, advancedOptions])
    • unregister(topicURI)
    • Error handling
    • Custom attributes for Advanced Options
  • Using custom serializer
  • Connecting through TLS in node environment
  • Tests and code coverage
  • Copyright and License
  • See Also

<!-- TOC -->

Description

Wampy.js is a TypeScript 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. The package ships with full TypeScript type declarations (.d.ts) out of the box. 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:

• Authentication:
  • Ticket-based Authentication
  • Challenge Response Authentication (wampcra method)
  • Cryptosign-based Authentication (cryptosign method)
• publisher:
  • subscriber black-white listing
  • publisher exclusion
  • publisher identification
  • payload passthru mode
  • event retention
• subscriber:
  • pattern-based subscription
  • publication trust levels
  • publisher identification
  • payload passthru mode
  • event retention
• caller:
  • caller identification
  • progressive call invocations
  • progressive call results
  • call canceling
  • call timeout
  • payload passthru mode
• callee:
  • caller identification
  • progressive call invocations
  • progressive call results
  • call trust levels
  • pattern-based registration
  • shared registration
  • payload passthru mode

Wampy supports the following serializers:

• JSON (default, native)
• MsgPack (See [MessagePack][] Site for more info)
• CBOR (See [CBOR][] Site for more info)
• Any new serializer can be easily added

In node.js environment Wampy is compatible with the following websocket clients:

• [WebSocket-Node][]. A WebSocket Implementation for Node.js (Draft-08 through the final RFC 6455)
• [ws][]. Simple to use, blazing fast and thoroughly tested WebSocket client and server for Node.js

For convenience, all API documentation is also available as a GitBook here.

Back to Table of Contents

Usage example

import { Wampy } from 'wampy';

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

Back to Table of Contents

Installation

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 all auth plugins and serializers. They are available as global objects:

window.JsonSerializer = JsonSerializer;
window.MsgpackSerializer = MsgpackSerializer;
window.CborSerializer = CborSerializer;
// WampyCra is not available in the browser bundle due to its dependency on node:crypto
window.WampyCryptosign = wampyCryptosign;

<script src="wampy-all.min.js"></script>

If you don't plan to use other serializers then JSON or any auth plugins, just include wampy.min.js.

<script src="wampy.min.js"></script>

Back to Table of Contents

Exported components

Wampy.js exports the following components that you can import as needed. All exports include TypeScript type declarations (.d.ts):

{
    "exports": {
        ".": {  // Main Wampy class
            "types": "./dist/esm/wampy.d.ts",
            "import": "./dist/esm/wampy.js",
            "require": "./dist/cjs/wampy.cjs"
        },
        "./JsonSerializer.js": {
            "types": "./dist/esm/serializers/json-serializer.d.ts",
            "import": "./dist/esm/serializers/json-serializer.js",
            "require": "./dist/cjs/serializers/json-serializer.cjs"
        },
        "./CborSerializer.js": {
            "types": "./dist/esm/serializers/cbor-serializer.d.ts",
            "import": "./dist/esm/serializers/cbor-serializer.js",
            "require": "./dist/cjs/serializers/cbor-serializer.cjs"
        },
        "./MsgpackSerializer.js": {
            "types": "./dist/esm/serializers/msgpack-serializer.d.ts",
            "import": "./dist/esm/serializers/msgpack-serializer.js",
            "require": "./dist/cjs/serializers/msgpack-serializer.cjs"
        },
        "./cryptosign.js": {    // Cryptosign authentication plugin
            "types": "./dist/esm/auth/cryptosign/wampy-cryptosign.d.ts",
            "import": "./dist/esm/auth/cryptosign/wampy-cryptosign.js",
            "require": "./dist/cjs/auth/cryptosign/wampy-cryptosign.cjs"
        },
        "./wampcra.js": {       // WAMP-CRA authentication plugin
            "types": "./dist/esm/auth/wampcra/wampy-cra.d.ts",
            "import": "./dist/esm/auth/wampcra/wampy-cra.js",
            "require": "./dist/cjs/auth/wampcra/wampy-cra.mjs"
        }
    }
}

Back to Table of Contents

CLI tool

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 using npx:

npm install -g wampy
# After that 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.

Migrating or Updating versions

Please refer to Migrating.md for instructions on upgrading major versions.

Back to Table of Contents

API

Below is a description of the exposed public API. Wampy ships with built-in TypeScript type declarations — no separate @types/wampy package is needed.

Constructor([url[, options]])

Wampy constructor can take 2 parameters:

• url to wamp server - optional. URL can be specified in the following forms:
  • Undefined/null. In-browser environment "page-scheme://page-server:page-port/ws" will b