JavaScript Client

powerful. fast. easy.

The AMPS JavaScript Client lets you write cross-platform messaging applications for both web apps working in a browser, as well as server-side applications that use Node.js. It uses the power of WebSocket technology combined with asyncronous nature of JavaScript.

Quick Start

Once the client is downloaded, it can be used in your JavaScript/TypeScript projects:

Node.js
1 var amps = require('amps');
2 console.log(amps.Client.version());

TypeScript / ES6
 1 // NPM installation: Import everything at once
 2 import * as amps from 'amps';
 3 console.log(amps.Client.version());
 4 
 5 // or
 6 
 7 // NPM installation: This way the final bundle can be smaller
 8 import { Client, Command } from 'amps';
 9 console.log(Client.version());
10 
11 // Manual installation (don't forget to add a typing reference):
12 /// <reference path="./amps.d.ts" />
13 import * as amps from './amps';
14 import { Client, Command } from './amps';

Application That Uses AMD Modules
1 define(['dist/amps'], function(amps) {
2     console.log(amps.Client.version());
3 }

Global Import in Browsers
1 <!-- Optional import, provides support for obsolete browsers like IE11 -->
2 <script src="es6-promise.min.js"></script>
3 <script src="amps.js"></script>

You are now ready to use AMPS in your project!

Here are a few JavaScript examples to get you started:

EXAMPLE 1: CONNECT AND SUBSCRIBE

In this example, we connect to an AMPS server running locally and initiate a subscription to the orders topic.

 1 var client = new amps.Client('my-application');
 2 
 3 client.connect('ws://localhost:9100/amps/json')
 4     .then(function() {
 5         // Connected, let's subscribe to a topic now
 6         return client.subscribe(
 7             function(message) {
 8                 console.log(message.data);
 9             }, 
10             'orders'
11         );
12     })
13 
14     // Once we subscribed, the subscriptionId is passed down the chain
15     .then(function(subscriptionId) {  
16         console.log(subscriptionId);
17         client.publish('orders', {order: 'Tesla 3', qty: 10});
18     })
19 	.catch(function(error) {
20         // This can be either a connection error or a subscription error, thanks to Promises!
21         return console.log(error);
22     });

As new orders are posted, the message handler is invoked with each message, and prints the data of each order to the console. Since every command (except publish()) returns a Promise, it is very easy to chain commands and handle errors:

 1 function onMessage(message) {
 2     console.log('message: ', message);
 3 }
 4 
 5 client.connect('ws://localhost:9100/amps/json')
 6     .then(() => client.subscribe(onMessage, 'orders'))         // connected, subscribe for the first topic
 7     .then(() => client.subscribe(onMessage, 'reservations'))   // second subscription
 8     .then(() => client.subscribe(onMessage, 'notifications'))  // third subscription
 9 	.catch(function(error) {
10         // if any subscription failed, the chain will end up here
11         return console.log(error);
12     });


EXAMPLE 2: PUBLISH A MESSAGE

With AMPS, publishing is simple, as shown in this example. We connect to an AMPS server running locally, and publish a single message to the messages topic. To simply publish a message, there is no need to predeclare the topic or configure complex routing. Any subscription that has asked for XML messages on the messages topic will receive the message.

1 var client = new amps.Client('publish-example');
2 
3 client.connect('ws://localhost:9100/amps/xml')
4     .then(function() {
5         client.publish('messages', '<hi>Hello, world!</hi>');
6     })
7     .catch(function(err) {
8         console.log(error);
9     });

EXAMPLE 3: DISCONNECT HANDLING

In this example, we need to be subscribed to the orders topic, even if connectivity to our AMPS server is temporarily interrupted. We use a reconnect function to enable recovery from a connection error. When AMPS detects a connection error, the reconnect function is called from errorHandler to re-establish connection, and our onConnect method subscribes to the topic again once a successful connection is made. Notice that the errorHandler is only called after a successful connection has been established, otherwise a connection error is caught by the catch callback of the connect Promise.

 1 // Assign an error handler that will handle general error such as disconnects
 2 var client = new amps.Client('my-app').errorHandler(function(err) {
 3     console.log(err, 'Reconnecting after 5 seconds...');
 4     setTimeout(reconnect, 5000);
 5 });
 6 
 7 function reconnect() {
 8     return client
 9         .connect('wss://localhost:9100/amps/json')
10         .then(onConnect)
11         .catch(function(err) {
12             // Connection error occurred
13             setTimeout(reconnect, 5000);
14         });
15 }
16 
17 function onConnect() {
18     return client
19         .subscribe(function(message) {
20             console.log('message: ', message);
21         }, 'orders')
22         .catch(function(err) {
23             console.log('Subscription error: ', err);
24         });
25 }
26 
27 // Begin by connecting and subscribing
28 reconnect(onConnect);

EXAMPLE 4: QUERY THE CONTENTS OF A STATE-OF-THE-WORLD TOPIC

State-of-the-World ("SOW") topics in AMPS combine the power of a database table with the performance of a publish-subscribe system. Use the AMPS JavaScript client to query the contents of a SOW topic.

 1 var client = new amps.Client('my-application');
 2 
 3 client.connect('ws://localhost:9100/amps/json')
 4     .then(function() {
 5         return client.sow(
 6             function(message) {
 7                 if (message.header.command() == 'sow') {
 8                     console.log(message.data);
 9                 }
10             },
11             'orders',
12             "/symbol='ROL'",
13             {
14                 batchSize: 100,
15                 timeout: 5000
16             }
17         );
18     })
19 	.catch(function(error) {
20         console.error('Error: ', error);
21 	});

This example queries for all orders for the symbol ROL, and simply prints the messages to the console.

EXAMPLE 5: COMMAND INTERFACE

Even though AMPS clients provide the above named convenience methods for core AMPS functionality, you can use the Command object to customize the messages that AMPS sends. This is useful for more advanced scenarios where you need precise control over the message, or in cases where you need to use an earlier version of the client to communicate with a more recent version of AMPS, or in cases where a named method is not available.

 1 var client = new amps.Client('my-application');
 2 
 3 client.connect('ws://localhost:9100/amps/json')
 4     .then(function() {
 5         var subscribeCommand = new amps.Command('subscribe')
 6                                    .topic('messages')
 7                                    .filter('/id > 20');
 8 
 9         return client.execute(subscribeCommand, function(message) {
10             console.log('message: ', message.data);
11         });
12     })
13     .catch(function(error) {
14         console.error('Error: ', error);
15     });

This example provides the subscription to a messages topic with a filter applied.

AMPS Server Configuration for Websockets

To configure AMPS for Websocket support, you need to specify the following Transport:

1 <Transports>
2     <Transport>
3         <Name>json-websocket</Name>
4         <Type>tcp</Type>
5         <Protocol>websocket</Protocol>
6         <InetAddr>9100</InetAddr>
7         <MessageType>json</MessageType>
8     </Transport>
9 </Transports>

With the above configuration, AMPS will listen for incoming Websocket connections on port 9100 and will support the json message type. To use TLS/SSL, you'd specify a Certificate and PrivateKey (and optionally the Ciphers):

 1 <Transport>
 2     <Name>json-websocket-secure</Name>
 3     <Type>tcp</Type>
 4     <Protocol>websocket</Protocol>
 5     <InetAddr>9443</InetAddr>
 6     <MessageType>json</MessageType>
 7     <Certificate>./cert.pem</Certificate>
 8     <PrivateKey>./key.pem</PrivateKey>
 9     <Ciphers>HIGH:!aNULL:!MD5:@STRENGTH</Ciphers>
10 </Transport>

Authentication

AMPS provides an option for websocket protocol that controls authentication: WWWAuthenticate. This option provides a flexible way of setting up authorization for the JavaScript client.

The option can have the following values:

  • Negotiate (Kerberos)
  • NTLM
  • Basic realm="Secure Area"

When using Negotiate or NTLM, you don't have to do anything from the JavaScript client: authentication is automatically handled by browser/environment. When using Basic Auth (we recommend using wss in this scenario), you'll need to set a URI of the form wss://user:password@ip:port/amps/json.

By default, no authentication is performed until the 'logon' command is performed after connection.

In order to enable authentication for the AMPS JavaScript client, you need to specify the following settings:

  1. Add a protocol in the Protocols section of the config:
    1 <Protocol>
    2     <Name>websocket-portal</Name>
    3     <Module>websocket</Module>
    4     <WWWAuthenticate>Basic realm="Secure Area"</WWWAuthenticate> <!-- Basic Auth -->
    5     <WWWAuthenticate>Negotiate</WWWAuthenticate> <!-- Kerberos-->
    6     <WWWAuthenticate>NTLM</WWWAuthenticate> <!-- NTLM -->
    7 </Protocol>
  2. Specify a transport in the Transports section of the config that will be used for the JavaScript client:
    1 <Transport>
    2     <Name>websocket-auth</Name>
    3     <Type>tcp</Type>
    4     <Protocol>websocket-portal</Protocol>
    5     <InetAddr>9002</InetAddr>
    6 </Transport>

EVERYTHING YOU NEED

If you need more help getting started, the 60East Technologies support and services team is ready to provide the support you need to help you CRANK UP THE AMPS.

The current release of the JavaScript client is version 5.2.2.0, which supports AMPS servers version 5.2 and later.

Documentation

HERE'S THE GOOD STUFF.

If you're ready to CRANK IT UP, here's the information you need to get started. Choose the guide you're looking for, or download a ZIP file with all of the docs.

Visit Documentation Download Documentation