Chapter 5. Using the API

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.

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");
});

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.

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.

var rhea = require("rhea");
var container = rhea.create_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.

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

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.

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

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

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

container.connect(opts);

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.

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.

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

container.connect(opts);

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.

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

container.connect(opts);

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

container.connect(opts);

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.

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

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.

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.

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

container.connect(opts);

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

container.connect(opts);

AMQ JavaScript can authenticate connections with a user and password.

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

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

container.connect(opts);

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

container.connect(opts);

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.