Bunnies

Microservices Actor Toolchain for RabbitMQ

Build more services faster, better and with more smiles.

Extracted out of patterns used in my work on a multitute of live systems.

Simplifies an abstracts the creation of actors that respond to messages received via AMQP.

Each actor maintains its own single queue of messages from which it pulls and reacts to messages.

Sane defaults for managing amqp state make previously tedious code warm and fuzzy, like a bunny.

Architecture

According to AMQP best practices bunnies will connect a single socket to the AMQP server provided by the AMQP_URL environment variable. This singleton connection is used automatically when starting all actors, unless another connection is specified explicitly.

You can also get a handle on the singleton connection by running

import { getConnection } from 'bunnies';

let connection = await getConnection();

getConnection will always return a single connection reused by all callers in a given process.

Library

Each actor consumes messages from a single rabbitmq queue. On startup the actor will establish connection with your AMQP server, assert the specified exchange and queue, and bind the queue to the exchange with the routing key.

Usage

import { Actor, log } from 'bunnies';

import { connect } from 'amqplib';

(async () => {

  // connects to AMQP_URL environment variable

  let actor = Actor.create({

    exchange: 'orders',

    routingkey: 'ordercreated',

    queue: 'printorderreceipt'

  });

  await actor.start(async (channel, msg) => {

    log.info('print order receipt', msg.content.toString());

    await channel.ack(msg);

    log.info('message acknowledged', msg.content.toString());

  });

  // publish example message with order uid as content

  let buffer = new Buffer('cf9418e8-eb0f-4c7e-88a3-4aca045a30f2');

  await actor.channel.publish('orders', 'ordercreated', buffer);

})();

Re-Using An Existing AMQP Connection

It may not be idea to connect a separate TCP socket for every single actor. Instead, optionally provide an amqp.Connection when creating Actor.

import { connect, Connection } from 'amqplib';

let connection: Connection = await connect();

let actor = Actor.create({
  
  exchange,

  routingkey,

  queue,

  connection

})

The above will still create a new channel but will re-use the existing connection.

Events

Each actor is also an Event Emitter, emitting the following events:

• exchange.created

• queue.created

• binding.created

• amqp.connected

• amqp.disconnected

• message.received

• message.acked

• message.nacked

• error

File System

Actors are exported as javascript modules. Each module must export an Actor which implements the bunnies.Actor interface.

Command Line Tool

Microservices can be run one or more at a time from the command line using the bunnies command.

To run all actors

sh> bunnies --dir=./actors

sh> bunnies -a actors/matcher.js -a actors/rpc.js -a actors/websocket.js

sh> bunnies -bind universalgoldtrust|payments|ugt.payments
-queue ugt.payments
-exec process_payments.sh
-cleanup