hermoth v3.1.0

Hermoth

Norse Messenger God

A wrapper for an AMQP-compatible message broker.

Installation

npm install hermoth

Running locally

npm install
npm test

Usage

import Hermoth from 'hermoth'

const hermoth = new Hermoth(options) // see below for `options` examples in use case sections

// connect or create the exchange and the queue, and start consuming messages
hermoth.init()

Subscribe to messages:

hermoth.subscribe('my-message-name', function consume(msg) {
  console.log(msg)
})

Publish messages:

const msg = { someData: {} }
hermoth.publish('my-message-name', msg )

Use cases

At @velocityapp we have multiple instances (replicas) of the same service running in parallel.

Some messages need to be received by all instances of the application and processed , but some need to be received and processed by a single instance of the same application type only. You can find how to configure Hermoth to satisfy both needs below.

Use case 1: Only one instance of the same application type receives the message

You can achieve this by creating a queue with a specific name, and have the instances connect to this queue.

The message broker will deliver the messages in round robin fashion per spec (competing consumers pattern)

import Hermoth from 'hermoth'

const worker = new Hermoth({
  host: 'amqp://localhost:5672',
  exchangeName: 'exchange_name',
  queueName: 'my_service_queue',
  durable: true
})

Use case 2: All instances of the same application type receives the same message

You can achieve this by having each instance of the application creating their own anonymous and disposable queues. Notice we don't pass a queueName to the constructor; the broker to generate a random one for us.

import Hermoth from 'hermoth'

const consumer = new Hermoth({
  host: 'amqp://localhost:5672',
  exchangeName: 'exchange_name',
  exclusiveQueue: true
})

Message persistence

Preventing messages getting lost when they are in the consumer

To prevent messages getting lost when they were being processed by a consumer; pass noAck = true and acknowledge the processing of the message. It's very important to acknowledge the message or else the broker will keep re-queueing and delivering it.

import Hermoth from 'hermoth'

const worker = new Hermoth({
  // the options of one of the use cases, plus;
  noAck: false
})

worker.subscribe('message:type', function consume(msg, originalMessage) {
  process(msg.payload)
  this.channel.ack(originalMessage)
})

Preventing messages getting lost when they are in the queue

To prevent messages getting lost if the message broker crashes, you need to mark both the queue and the messages as durable. When marked as durable, the message broker will save them to the disk.

import Hermoth from 'hermoth'

const worker = new Hermoth({
  // the options of one of the use cases, plus;
  durableQueue: true,
  persistentMessages: true
})