Chapter 5. Using the API

This chapter explains how to use the AMQ JavaScript API to perform common messaging tasks.

5.1. Basic operation

5.1.1. Handling messaging events

AMQ JavaScript is an asynchronous event-driven API. To define how the application handles events, the user registers event-handling functions on the container object. These functions are then called as network activity or timers trigger new events.

Example: Handling messaging events

var rhea = require("rhea");
var container = rhea.create_container();

container.on("sendable", function (event) {
    console.log("A message can be sent");
});

container.on("message", function (event) {
    console.log("A message is received");
});

These are only a few common-case events. The full set is documented in the API reference.

5.1.2. Creating a container

The container is the top-level API object. It is the entry point for creating connections, and it is responsible for running the main event loop. It is often constructed with a global event handler.

Example: Creating a container

var rhea = require("rhea");
var container = rhea.create_container();

Setting the container identity

Each container instance has a unique identity called the container ID. When AMQ JavaScript makes a network connection, it sends the container ID to the remote peer. To set the container ID, pass the id option to the create_container method.

Example: Setting the container identity

var container = rhea.create_container({"id": "job-processor-3"});

If the user does not set the ID, the library will generate a UUID when the container is constucted.

5.2. Network connections

5.2.1. Creating outgoing connections

To connect to a remote server, pass connection options containing the host and port to the container.connect() method.

Example: Creating outgoing connections

container.on("connection_open", function (event) {
    console.log("Connection " + event.connection + " is open");
});

var opts = {
    "host": "example.com",
    "port": 5672
};

container.connect(opts);

The default host is localhost. The default port is 5672.

See the Section 5.3, “Security” section for information about creating secure connections.

5.2.2. Configuring reconnect

Reconnect allows a client to recover from lost connections. It is used to ensure that the components in a distributed system reestablish communication after temporary network or component failures.

AMQ JavaScript enables reconnect by default. If a connection attempt fails, the client will try again after a brief delay. The delay increases exponentially for each new attempt, up to a default maximum of 60 seconds.

To disable reconnect, set the reconnect connection option to false.

Example: Disabling reconnect

var opts = {
    "host": "example.com",
    "reconnect": false
};

container.connect(opts);

To control the delays between connection attempts, set the initial_reconnect_delay and max_reconnect_delay connection options. Delay options are specified in milliseconds.

To limit the number of reconnect attempts, set the reconnect_limit option.

Example: Configuring reconnect

var opts = {
    "host": "example.com",
    "initial_reconnect_delay": 100,
    "max_reconnect_delay": 60 * 1000,
    "reconnect_limit": 10
};

container.connect(opts);

5.2.3. Configuring failover

AMQ JavaScript allows you to configure alternate connection endpoints programatically.

To specify multiple connection endpoints, define a function that returns new connection options and pass the function in the connection_details option. The function is called once for each connection attempt.

Example: Configuring failover

var hosts = ["alpha.example.com", "beta.example.com"];
var index = -1;

function failover_fn() {
    index += 1;

    if (index == hosts.length) index = 0;

    return {"host": hosts[index].hostname};
};

var opts = {
    "host": "example.com",
    "connection_details": failover_fn
}

container.connect(opts);

This example implements repeating round-robin failover for a list of hosts. You can use this interface to implement your own failover behavior.

5.3. Security

5.3.1. Securing connections with SSL/TLS

AMQ JavaScript uses SSL/TLS to encrypt communication between clients and servers.

To connect to a remote server with SSL/TLS, set the transport connection option to tls.

Example: Enabling SSL/TLS

var opts = {
    "host": "example.com",
    "port": 5671,
    "transport": "tls"
};

container.connect(opts);

Note

By default, the client will reject connections to servers with untrusted certificates. This is sometimes the case in test environments. To bypass certificate authorization, set the rejectUnauthorized connection option to false. Be aware that this compromises the security of your connection.

5.3.2. Connecting with a user and password

AMQ JavaScript can authenticate connections with a user and password.

To specify the credentials used for authentication, set the username and password connection options.

Example: Connecting with a user and password

var opts = {
    "host": "example.com",
    "username": "alice",
    "password": "secret"
};

container.connect(opts);

5.3.3. Configuring SASL authentication

AMQ JavaScript uses the SASL protocol to perform authentication. SASL can use a number of different authentication mechanisms. When two network peers connect, they exchange their allowed mechanisms, and the strongest mechanism allowed by both is selected.

AMQ JavaScript enables SASL mechanisms based on the presence of user and password information. If the user and password are both specified, PLAIN is used. If only a user is specified, ANONYMOUS is used. If neither is specified, SASL is disabled.

5.4. More information

For more information, see the API reference.