Autobahn Legacy (WAMP v1) documentation

This page contains materials concerning Autobahn|JS 0.8.2, the last version of Autobahn|JS to implement version 1 of WAMP.

This version is now in maintenance mode.

Be aware that the following materials are no longer updated.

Downloads

  1. Production (minimized and gzipped)
  2. Production (only minimized)
  3. Development

Note

You can use the above via direct linking for development purposes, but do not hotlink for production. This will not work, since we place restrictions on HTTP referrers.

In addition, the source code is still accessible in the project GitHub repository.

Example code

Example code for various aspects of the use of Autobahn|JS can be found in the Autobahn|Python GitHub repository

API Reference

The following is a complete reference of the public application programming interface of AutobahnJS (which supplies WAMP functionality and wraps WebSocket).

Anything not listed here should be considered library internal and not be used from user applications

Deferreds and Promises

Note

For the purposes of this document, the terms Promise, Deferred and Future are used synonymous.

AutobahnJS relies on Promises for asynchronous programming. For example, when you issue an RPC, the immediate return value you will get back is a Promise object.

A promise is an object that represents the eventual value returned from the completion of an asynchronous operation (such as a RPC).

A promise has the following characteristics:

  1. Can be in one of three states: unfulfilled, resolved, rejected
  2. May only change from unfulfilled to resolved or unfulfilled to rejected
  3. Implements a then() method for registering callbacks for notification of state change
  4. Callbacks cannot change the value produced by the promise
  5. A promise’s then() method returns a new promise, to provide chaining while keeping the original promise’s value unchanged

Source: [*]

With JavaScript, promises are not built into the language, but come with libraries. There are different implementations. AutobahnJS comes with when.js promises built in, but allows to plug in a different promise implementation when needed.

when.js is a well tested and maintained JavaScript promise implementation conforming to the upcoming Common JS Promises/A proposal . We expect the when.js promises used (per default) by AutobahnJS to be interchangable and interoperable with other implementations conforming to Common JS Promises/A .

Details about how to change the promises module to be used are given in the Pluggable Promises section below.

Resources

Session Lifecycle

AutobahnJS provides different methods of session establishment - from low-level to high-level:

  • ab.Session

    Create a raw WAMP session object.

  • ab.connect

    WAMP session establishment with automatic reconnect.

  • ab.launch

    WAMP session establishment with automatic reconnect and authentication (WAMP-CRA).

ab.session

Creates a new WAMP session object

ab.Session(wsuri, onopen, onclose, options)
Arguments:
  • wsuri (string) – WebSocket URI of WAMP server.
  • onopen (function) – Callback fired when session has been estanlished.
  • onclose (function) – Callback fired when session has been closed, lost or failed to be established in the first place.
  • options (object) – WAMP session options.
Returns:

(object) new session object

ab.connect

Connect to WAMP server, establishing new session. High level function with auto-reconnect.

ab.connect(wsuri, onconnect, onhangup, options)
Arguments:
  • wsuri (string) – WebSocket URI of WAMP server.
  • onconnect (function) – Callback fired when session has been established.
  • onhangup (function) – Callback fired when session has been closed, lost or failed to be established in the first place.
  • options (object) – WAMP session options.
ab.connect(
   // The WebSocket URI of the WAMP server
   wsuri,

   // The onconnect handler
   function (session) {
      // WAMP session established here ..
   },

   // The onhangup handler
   function (code, reason, detail) {
      // WAMP session closed here ..
   },

   // The session options
   {
      'maxRetries': 60,
      'retryDelay': 2000
   }
);
  • The ‘onhangup’ handler is optional. If no handler is given, then the code and the reason are logged to the browser console.

  • The ‘onhangup’ handler is fired both in case of a failure to initially establish a connection, and should the established connection fail.

  • Possible ‘options’ are

    • ‘maxRetries’: The number of attempts that AutobahnJS makes at (re)establishing a connection.
    • ‘retryDelay’: The time in milliseconds between retries.
    • ‘skipSubprotocolCheck’: boolean, if ‘true’ the subprotocol check for whether the server speaks WAMP is skipped. May be useful with some browsers which do not provide subprotocol information.
    • ‘skipSubprotocolAnnounce’: boolean, if ‘true’ the subprotocol announcement (for WAMP) is skipped. May be useful when trying to connect to servers which do not handle WebSocket subprotocols handshaking.

ab.launch

Connect to WAMP server, establishing new session. High level function with auto-reconnect and authentication.

ab.launch(appconfig, onconnect, onhangup)
Arguments:
  • appconfig (object) – WAMP app configuration.
  • onconnect (function) – Callback fired when session has been established.
  • onhangup (function) – Callback fired when session has been closed, lost or failed to be established in the first place.
ab.launch(
   // WAMP app configuration
   {
      // Tavendo WebMQ server URL
      wsuri: ab.getServerUrl(),
      // authentication info
      appkey: null, // authenticate as anonymous
      appsecret: null,
      appextra: null,
      // additional session configuration
      sessionConfig: {maxRetries: 10,
                      sessionIdent: "Vote"}
   },
   // session open handler
   function (newSession) {
      sess = newSession;
      main(sess);
   },
   // session close handler
   function (code, reason, detail) {
      sess = null;
   }
);

session.sessionid

Return the WAMP session ID of for this session.

wampSession.sessionid()
Returns:(string) - The ID of this session or null if session is not open.
var mySessionId = wampSession.sessionid();

The session ID is used for sending published events to specific recipients, or to exclude recipients from receiving an event.

session.close

Close the session.

wampSession.close()
sess.close();

Session Authentication

Describe WAMP-CRA (WAMP Challenge Response Authentication).

session.authreq

Issues an authentication request.

wampSession.authreq(authkey, extra)
Arguments:
  • authkey (string) – Authentication key, i.e. user or application name. If undefined, anonymous authentication is performed.
  • extra (object) – Authentication extra information - optional.
Returns:

(deferred object) A deferred, the success handler of which will be fired with an authentication challenge.

Below are two full examples of an authentication handshake: one for authentication as anonymous, one using an authentication key and secret.

// Authenticate as anonymous

sess.authreq().then(function () {
   sess.auth().then(function(permissions) {
      // do your stuff
   }, onAuthError);
}, autreqError);
// Authenticate using authkey and authsecret

sess.authreq(authkey).then(
   function (challenge) {
      var signature = sess.authsign(challenge, authsecret);
      sess.auth(signature).then(function(permissions){
         // do your stuff
      }, onAuthError);
   }, autreqError);

‘Extra’ is a dictionary. The functions that the ‘extra’ serves are up to the implementation. Data in the ‘extra’ can e.g. be used to define a role for the user.

session.authsign

Signs an authentication challenge.

wampSession.authsign(challenge, secret)
Arguments:
  • challenge (string) – Authentication challenge as returned by the WAMP server upon a authentication request.
  • secret (string) – Authentication secret.
Returns:

(string) Authentication signature. This is then given to wampSession.auth to finish the authentication handshake.

var signature = sess.authsign(challenge, authsecret);

Signing of the challenge may be using the cleartext password, as shown above.

When the server stores the password hashed and salted, WAMP offers a function to derive the secret as stored on the server, and sign using this. In these cases the challenge string contains the salt the server used.

var secret = ab.deriveKey(authsecret, JSON.parse(challenge).authextra);

var signature = sess.authsign(challenge, secret);

Signing may also be via a third party, e.g. the Web server that the application is served from and to which it already is authenticated.

This could use something like this example function for the signing request:

function authsignremote(url, challenge) {

   var res = new XMLHttpRequest();
   res.open('POST', url, false);
   res.send(challenge);

   if (res.status == 200) {
      try {
         var r = res.responseText;
         console.log(r);
         return r;
      } catch (e) {
         return null;
      }
   } else {
      return null;
   }
};

and the signature would then be created like

var signature = authsignremote("/authsign", challenge);

session.auth

Authenticate, finishing the authentication handshake.

wampSession.auth(signature)
Arguments:
  • signature (string) – A authentication signature.
Returns:

(deferred object) A deferred, the success handler of which will be fired with the granted permissions.

sess.auth(response).then(function(permissions){
   // do your stuff
}, onAuthError);

Publish and Subscribe

session.subscribe

Subscribe to a given topic, subsequently receive events published under the topic.

wampSession.subscribe(topic, callback)
Arguments:
  • topic (string) – An URI or CURIE of the topic to subscribe to.
  • callback (function) – The event handler to fire when receiving an event under the subscribed topic.
sess.subscribe("http://example.com/event#myevent1", function (topic, event) {
   console.log("Event 1 received!");
});

Notes

  • The method runs asynchronously and does not provide feedback whether a subscription was successful or not.
  • A subscription may fail for example, when the WAMP server employs topic-based authorization and the client is not authorized to access or subscribe to the respective topic.
  • The topic can be specified either using a fully qualified URI, or a CURIE for which a prefix shorthand was previously established on the session.

You can hook up one callback to multiple topics, and since your callbacks will receive the topic for which they get fired, switch in your callback:

function myCallback(topic, event) {

   switch (topic) {
      case "http://example.com/event#myevent1":
         // handle event 1
         break;
      case "http://example.com/event#myevent2":
         // handle event 2
         break;
      default:
         break;
   }
};

sess.subscribe("http://example.com/event#myevent1", myCallback);
sess.subscribe("http://example.com/event#myevent2", myCallback);

You can also hook up multiple callbacks to the same topic:

var myEvent1Topic = "http://example.com/event#myevent1";

sess.subscribe(myEvent1Topic, function (topic, event) {
   // first code to handle event 1
});

sess.subscribe(myEvent1Topic, function (topic, event) {
   // more code to handle event 1
});

Notes

  • Upon the first subscribe to a topic, a WAMP message is sent to the server to subscribe the WAMP client for that topic.
  • Subsequent subscribes for a topic already previously subscribed to do not trigger a send of another WAMP message. The client already has a subscription, and merely registers (client side) the additional callback to be fired for events received on the respective topic.
  • A subscribe to a topic and for a callback that is already registered raises an exception.
  • Multiple callbacks registered for one topic are fired in the order they were registered.

session.unsubscribe

Unsubscribe any callback(s) currently subscribed from the given topic.

wampSession.unsubscribe(topic)
Arguments:
  • topic (string) – The URI or CURIE of the topic to unsubscribe from.
var myTopic = "http://example.com/myEvent1Topic";

sess.subscribe(myTopic, topicHandler1);
sess.subscribe(myTopic, topicHandler2);

sess.unsubscribe(myTopic);

In the above example, events for ‘myTopic’ are no longer received, and neither callback handler is fired.

session.unsubscribe

Unsubscribe only the given callback currently subscribed from the given topic.

wampSession.unsubscribe(topic, callback)
Arguments:
  • topic (string) – The URI or CURIE of the topic to unsubscribe from.
  • callback (function) – The event handler for which to remove the subscription.
var myTopic = "http://example.com/myEvent1Topic";

sess.subscribe(myTopic, topicHandler1);
sess.subscribe(myTopic, topicHandler2);

sess.unsubscribe(myTopic, topicHandler1);

In the above example, events for ‘myTopic’ are still received, but callback handler ‘topicHandler1’ is no longer called.

session.publish

Publish the given event (which may be of simple type, or any JSON serializable object) to the given topic.

wampSession.publish(topic, event)
Arguments:
  • topic (string) – The URI or CURIE of the topic to publish to.
  • event (object) – The event to be published.
var myTopic = "http://example.com/myEvent1Topic";
var myEvent = {eventname: "myEvent", eventDetails: ["something happened", "today"]};


sess.publish(myTopic, myEvent);

session.publish

Publish the given event (which may be of simple type, or any JSON serializable object) to the given topic, specifying whether to exclude myself or not.

wampSession.publish(topic, event, excludeMe)
Arguments:
  • topic (string) – The URI or CURIE of the topic to publish to.
  • event (object) – The event to be published.
  • excludeMe (bool) – Exclude me (the publisher) from the receivers for this publication (if I am subscribed)
var myEvent1Topic = "http://example.com/event#myevent1";

sess.subscribe(myEvent1Topic, function(topic, event){
   console.log(topic, event);
});

sess.publish(myEvent1Topic, "Hello world!", true);
sess.publish(myEvent1Topic, "Foobar!", false);

In the above example, only the publication of “Foobar” is sent to the publisher and logged.

session.publish

Publish the given event (which may be of simple type, or any JSON serializable object) to the given topic, specifying a group of clients that do not receive the event, or a group that receives the event.

wampSession.publish(topic, event, exclude, eligible)
Arguments:
  • topic (string) – The URI or CURIE of the topic to publish to.
  • event (object) – The event to be published.
  • exclude (array) – Explicit list of clients to exclude from this publication, given as array of session IDs.
  • eligible (array) – Explicit list of clients that are eligible for this publication, given as array of session IDs.
var myEvent1Topic = "http://example.com/event#myevent1";
var mySessionId = sess.sessionid();

sess.subscribe(myEvent1Topic, function(topic, event){
   console.log(topic, event);
});

sess.publish(myEvent1Topic, "Hello world!", [], [mySessionId] );
sess.publish(myEvent1Topic, "Foobar!", [client1SessionId, client23SessionId], [mySessionId]);

In the above example, the first publish is equivalent to setting the option ‘excludeMe’ to true.

In the second publish, Clients 1 & 23 would not receive the event, while all other subscribed clients would receive it - including the sender.

Remote Procedure Calls

session.call

Publish the given event (which may be of simple type, or any JSON serializable object) to the given topic.

wampSession.call(method, ...)
Arguments:
  • method (string) – The URI or CURIE of the remote procedure to call.
  • of object(s) ... (varargs) – Remote procedure call arguments, zero or more values.
Returns:

(deferred object) The call result deferred, upon which you can add success and error processing.

sess.call("http://example.com/rpc1", arg1, arg2, arg3).then(function (result) {
   // do stuff with the result
}, function(error) {
   // handle the error
});
  • The method to be called is identified by a valid HTTP URI.
  • The call may have zero or more arguments.
  • Both the success handler and the error handler receive a single return value. This may be any JSON object.
  • The error handler is optional.

URI Handling

session.prefix

Establish the given prefix for use in CURIEs in the session.

wampSession.prefix(prefix, uri)
Arguments:
  • prefix (string) – The prefix to be established for subsequent use in CURIEs.
  • uri (string) – The fully qualified URI to establish a CURIE prefix for.
sess.prefix("myEvents", "http://example.com/events/");
sess.prefix("myRPCs", "http://example.com/rpcs#");

sess.subscribe("myEvents:foo");
sess.call("myRPCs:bar").then(barSuccess, barError);

In the above, “myEvents:foo” is equivalent to “http://example.com/events/foo” and “myRPCs:bar” to “http://example.com/rpcs#bar”.

session.shrink

Shrink the given fully qualified URI to a CURIE. A CURIE prefix must have been previously defined in this session.

wampSession.shrink(uri, pass)
Arguments:
  • uri (string) – The fully qualified URI to be shrunk to CURIE.
  • pass (bool) – If argument present and true, return the unmodified URI when no prefix was defined previously in this session to shrink the URI.
sess.prefix("myEvents", "http://example.com/events/");

var foobar = sess.shrink("http://example.com/events/foobar");

In the above, “foobar” is assigned as “myEvents:foobar”.

session.resolve

Resolves the given CURIE to a fully qualified URI. The CURIE prefix must have been previously defined in this session.

wampSession.resolve(curie, pass)
Arguments:
  • curie (string) – Resolves the The fully qualified URI to establish a CURIE prefix for.
  • pass (bool) – If argument present and true, return the unmodified URI when no prefix was defined to.
sessi.prefix("myEvents", "http://example.com/events/");

var foobar = sess.resolve("myEvents:foobar");

In the above, “foobar” is assigned as “http://example.com/events/foobar”.

Settings and Diagnostics

ab.debug

Turn on/off debugging of WAMP and/or WebSocket communication.

ab.debug(wamp, ws)
Arguments:
  • wamp (bool) – If true, enable debugging of WAMP level communication.
  • ws (bool) – If true, enable debugging of WebSocket level communication.

ab.version

Return the AutobahnJS version.

ab.version()
Returns:(string) AutobahnJS version string.

Pluggable Promises

The promises module to be used can be set by changing the value of ab._Deferred from its default value of “when.defer”, e.g.

ab._Deferred = jQuery.Deferred;
Reactive Manifesto: We are reactive banner