stompit

The stompit.ChannelPool class manages a pool of STOMP channels to optimize connection reuse and limit concurrent channel allocation. Instead of manually managing connections, you request a channel from the pool, perform your operations (send/subscribe), and the pool handles the lifecycle based on idle events.

Requesting a channel

Use channelPool.channel(callback) to request an unused channel. The channel is passed to the callback as the second argument.

Important Lifecycle Note: The pool determines if a channel is available for reuse or should be closed based on the idle event. This event is emitted when all send and subscribe operations on that channel are completed. If you perform a single send operation and no other operations are active, the channel will immediately emit idle and may be returned to the pool or closed.

channelPool.channel(function(error, channel) {
  // Use the channel here
});

The stompit.Channel class provides a connectionless abstraction for reliable message sending and subscriptions. Unlike a standard stompit.Client, a Channel manages connections automatically based on its configuration.

Connection Management

You can control how the Channel manages its underlying connections using the alwaysConnected option in the constructor:

• alwaysConnected: false (Default): On-demand mode. A connection is maintained only while there are active operations (e.g., sending messages or open subscriptions). The connection is dropped once the last operation completes.
• alwaysConnected: true: The Channel maintains an open connection at all times.

To completely stop all operations and disconnect the underlying client (even in alwaysConnected mode), call channel.close().

const channel = new stompit.Channel(connectFailover, { alwaysConnected: true });

The options object passed to stompit.connect controls the connection behavior.

General Options

• host (string): Remote host address. Default: "localhost".
• port (integer): Remote port address. Default: 61613.
• timeout (integer): Timeout for the transport connect operation. Default: 3000.
• connectHeaders (object): Headers to be sent in the connect frame. Default: {}.
• path (string): Use unix domain socket and use path as the destination address.
• ssl (boolean): Use a secure connection. Default: false.
• connect (function): Override the transport factory constructor used.
• heartbeatDelayMargin (integer): Add milliseconds for server heart-beat wait interval. Default: 100.
• heartbeatOutputMargin (integer): Subtract milliseconds for client heart-beat start interval. Default: 0.

Note: Since net.connect and tls.connect are used under the hood, any undocumented options available to those Node.js functions are also applicable.

stompit is a STOMP client library for Node.js compatible with STOMP 1.0, 1.1, and 1.2. It uses a stream-oriented API and supports any stream.Duplex transport (e.g., tls.TLSSocket).

To use the client, follow these steps:

1. Define connectOptions including host, port, and connectHeaders (for authentication and heartbeats).
2. Call stompit.connect() to establish a connection.
3. Use client.send(sendHeaders) to create a writable stream for sending messages.
4. Use client.subscribe(subscribeHeaders, callback) to listen for incoming messages.
5. Within the subscription callback, use message.readString() to consume the message body.
6. Acknowledge the message using client.ack(message) if using client-side acknowledgment modes.
7. Disconnect using client.disconnect() when finished.

const stompit = require('stompit');

const connectOptions = {
  'host': 'localhost',
  'port': 61613,
  'connectHeaders':{
    'host': '/',
    'login': 'username',
    'passcode': 'password',
    'heart-beat': '5000,5000'
  }
};

stompit.connect(connectOptions, function(error, client) {
  
  if (error) {
    console.log('connect error ' + error.message);
    return;
  }
  
  const sendHeaders = {
    'destination': '/queue/test',
    'content-type': 'text/plain'
  };
  
  const frame = client.send(sendHeaders);
  frame.write('hello');
  frame.end();
  
  const subscribeHeaders = {
    'destination': '/queue/test',
    'ack': 'client-individual'
  };
  
  client.subscribe(subscribeHeaders, function(error, message) {
    
    if (error) {
      console.log('subscribe error ' + error.message);
      return;
    }
    
    message.readString('utf-8', function(error, body) {
      
      if (error) {
        console.log('read message error ' + error.message);
        return;
      }
      
      console.log('received message: ' + body);
      
      client.ack(message);
      
      client.disconnect();
    });
  });
});