stomp-client

A STOMP protocol implementation in node.js

Stomp Client

A node.js STOMP client. Props goes to Russell Haering for doing the initial legwork.

The following enhancements have been added:

  • Unit tests
  • Ability to support different protocol versions (1.0 or 1.1) - more work needed
  • Inbound frame validation (required / regex'able header values)
  • Support for UNSUBSCRIBE frames in client
  • Ability to add custom headers to SUBSCRIBE/UNSUBSCRIBE frames
  • ACK and NACK support
npm install stomp-client
var Stomp = require('stomp-client');
var destination = '/queue/someQueueName';
var client = new Stomp('127.0.0.1', 61613, 'user', 'pass');

client.connect(function(sessionId) {
    client.subscribe(destination, function(body, headers) {
      console.log('This is the body of a message on the subscribed queue:', body);
    });

    client.publish(destination, 'Oh herrow');
});

The client comes in two forms, a standard or secure client. The example below is using the standard client. To use the secure client simply change StompClient to SecureStompClient

API

The meaning of queue names is not defined by the STOMP spec, but by the Broker. However, with ActiveMQ, they should begin with "/queue/" or with "/topic/", see STOMP1.0 for more detail.

Require returns a constructor for STOMP client instances.

For backwards compatibility, require('stomp-client').StompClient is also supported.

  • address: address to connect to, default is "127.0.0.1"
  • port: port to connect to, default is 61613
  • user: user to authenticate as, default is ""
  • pass: password to authenticate with, default is ""
  • protocolVersion: see below, defaults to "1.0"
  • reconnectOpts: see below, defaults to {}

Protocol version negotiation is not currently supported and version "1.0" is the only supported version.

ReconnectOpts should contain an integer retries specifying the maximum number of reconnection attempts, and a delay which specifies the reconnection delay. (reconnection timings are calculated using exponential backoff. The first reconnection happens immediately, the second reconnection happens at +delay ms, the third at + 2*delay ms, etc).

Connect to the STOMP server. If the callbacks are provided, they will be attached on the 'connect' and 'error' event, respectively.

If using virtualhosts to namespace your queues, you must pass a version header of '1.1' otherwise it is ignored.

Disconnect from the STOMP server. The callback will be executed when disconnection is complete. No reconnections should be attempted, nor errors thrown as a result of this call.

  • queue: queue to subscribe to
  • headers: headers to add to the SUBSCRIBE message
  • callback: will be called with message body as first argument, and header object as the second argument
  • queue: queue to unsubscribe from
  • headers: headers to add to the UNSUBSCRIBE message
  • queue: queue to publish to
  • message: message to publish, a string or buffer
  • headers: headers to add to the PUBLISH message
  • messageId: the id of the message to ack/nack
  • subscription: the id of the subscription
  • transaction: optional transaction name

Returns whether or not the connection is currently writable. During normal operation this should be true, however if the client is in the process of reconnecting, this will be false.

Emitted on successful connect to the STOMP server.

Emitted on an error at either the TCP or STOMP protocol layer. An Error object will be passed. All error objects have a .message property, STOMP protocol errors may also have a .details property.

If the error was caused by a failure to reconnect after exceeding the number of reconnection attempts, the error object will have a reconnectionFailed property.

Emitted when the client has successfully reconnected. The event arguments are the new sessionId and the reconnection attempt number.

Emitted when the client has been disconnected for whatever reason, but is going to attempt to reconnect.

MIT