angular-wamp

Angular library for Autobahn.js (WAMP v2)

Usage no npm install needed!

<script type="module">
  import angularWamp from 'https://cdn.skypack.dev/angular-wamp';
</script>

README

AngularWAMP

AngularWAMP is an AngularJS wrapper for AutobahnJS (v 0.9.5) for WAMP v2 (Web Application Messaging Protocol).

It simplifies getting WAMP v2 integrated into your AngularJS application. For the most part, it's works just like AutobahnJS, with a couple of angular related changes, which are noted below.

What is this library used for?

This library allows you to use WebSockets in your AngularJS app with any language that support the WAMPv2 protocol. This includes, Python and PHP. For a complete list of WAMPv2 implementations, visit the implementations page on wamp.ws.

For more information on why WAMP is a great choice for your project, read: Why WAMP?

Installing AngularWAMP

With Bower

You can download the zip file or install AngularWAMP via Bower:

$ bower install angular-wamp --save

To use AngularWAMP in your project, you need to include the following files in your HTML:

<!-- AngularJS -->
<script src="https://ajax.googleapis.com/ajax/libs/angularjs/1.2.26/angular.min.js"></script>

<!-- AutobahnJS -->
<script src="bower_components/autobahn/autobahn.js"></script>

<!-- AngularWAMP -->
<script src="bower_components/angular-wamp/release/angular-wamp.js"></script>

With NPM

$ npm install angular-wamp

And then you can import angular-wamp into your js files:

import angular     from 'angular';
import angularWamp from 'angular-wamp';

// module definition
export default angular.module('app.starter', [angularWamp])
    .config(function($wampProvider) {
        $wampProvider.init({
            url: 'ws://127.0.0.1:9000/',
            realm: 'realm1'
            //Any other AutobahnJS options
        });
    })
    .run(function($wamp){
        $wamp.open();
    });

angular.bootstrap(document, ['app.starter']);

Documentation

Configuration

Before you can use AngularWAMP, you have to inject the 'vxWamp' module into your application.

var app = angular.module("myApp", ["vxWamp"]);

Then configure the connection settings, by passing an options object to $wampProvider.init().

app.config(function ($wampProvider) {
     $wampProvider.init({
        url: 'ws://127.0.0.1:9000/',
        realm: 'realm1'
        //Any other AutobahnJS options
     });
 })

Now the $wamp service is available to be injected into any controller, service or factory.

app.controller("MyCtrl", function($scope, $wamp) {

   // 1) subscribe to a topic
   function onevent(args) {
      $scope.hello = args[0];
   }
   $wamp.subscribe('com.myapp.hello', onevent).then(
    function (subscriptionObject) {
        console.log("Got subscription object : " + subscriptionObject);
    },
    function (err) {
        console.log("Error while subscribing to com.myapp.hello : " + err);
    }
   );

   // 2) publish an event
   $wamp.publish('com.myapp.hello', ['Hello, world!']);

   // 3) register a procedure for remoting
   function add2(args) {
      return args[0] + args[1];
   }
   $wamp.register('com.myapp.add2', add2);

   // 4) call a remote procedure
   $wamp.call('com.myapp.add2', [2, 3]).then(
      function (res) {
         $scope.add2 = res;
   });      
});

You'll notice that we did not need to wait for the connection to be established before making WAMP calls. That's because, all requests are queued until a connection is established.

Connecting

To open the connection you just need to call $wamp.open(). This can be done from anywhere that allows $wamp to be injected. If you want to open the connection right when the app starts, you can add it to .run().

    .run(function($wamp){
        $wamp.open();
    })

Events

One area that AngularWAMP differs from AutobahnJS, is in how onclose and onopen are handled. In AngularWAMP, they're events that are emitted globally. This has the added benefit of allowing the entire app be aware of the connection state.

app.controller("MainCtrl", function($scope, $wamp) {
    $scope.$on("$wamp.open", function (event, session) {
        console.log('We are connected to the WAMP Router!'); 
    });
    
    $scope.$on("$wamp.close", function (event, data) {
        $scope.reason = data.reason;
        $scope.details = data.details;
    });
            
});

Authentication

The other major change from AutobahnJS is authentication. The auth methods can be added to the connection options through the $wampProvider within .config().

app.config(function ($wampProvider) {
     $wampProvider.init({
        url: 'ws://127.0.0.1:9000/',
        realm: 'realm1'
        authmethods: ["myauth"]
     });
 })

If the router sends a Challenge Message, it gets emitted with the event $wamp.onchallange that has to return a promise.

note: This will probably change in the future, if I can figure out a better way to do this.

$scope.$on("$wamp.onchallenge", function (event, data) {
    if (data.method === "myauth"){                
        return data.promise.resolve(autobahn.auth_cra.sign('someSecret', data.extra.challenge));
     } 
     //You can also access the following objects:
     // data.session             
     //data.extra
});

Other Properties

You can also access the connection and session through the $wamp service:

$wamp.session;
$wamp.connection;

Multiple Connections

You can create multiple connections by creating a new provider that wraps $wampProvider. You'll also need to specify a prefix for that services wamp events, which will be used instead of $wamp.

app.provider('$wamp2', function ($wampProvider) {

        var options = {
            url: 'ws://127.0.0.1:9992',
            realm: 'thruway.auth',
            prefix: 'wamp2'
        };

        this.$get = function ($injector) {
            $wampProvider.init(options);
            return $injector.invoke($wampProvider.$get);
        };
    })

You can now use the service $wamp2 exactly like $wamp.

Interceptors

AngularWAMP supports $http style interceptors

The interceptors are service factories that are registered with the $wampProvider by adding them to the $wampProvider.interceptors array. The factory is called and injected with dependencies (if specified) and returns the interceptor.

At the moment only response interceptors are supported. There are two interceptors for each WAMP action. They're made up of the action name followed by Response or ResponseError for errors.

.factory('myWampInterceptor', function ($q) {


        return {

            // optional method
            'callResponse': function (response) {
                // do something on success
                return response;
            },

            // optional method
            'callResponseError': function (response) {
                // do something on error
                return response
            },

            // optional method
            'subscribeResponse': function (response) {

                //Mangle up the subscription response callback
                var r = response.result.handler;
                response.result.handler = function (args) {
                    args[0].name = "Mickey Mouse";
                    return r(args);
                };

                //You can also return a promise
                return $q.when(response);
            },

            // optional method
            'subscribeResponseError': function (response) {
                // do something on error
                return response;
            },
            // optional method
            'publishResponse': function (response) {
                // do something on success
                return response;
            },

            // optional method
            'publishResponseError': function (response) {
                // do something on error
                return response
            },
            // optional method
            'registerResponse': function (response) {
                // do something on success
                return response;
            },

            // optional method
            'registerResponseError': function (response) {
                // do something on error
                return response
            },
        };
    });



    $wampProvider.interceptors.push('myWampInterceptor');
    

For more information, you can reference the AutobahnJS documentation.