stackrabbit

StackRabbit [Beta]

Koa inspired(some might say copied) framework for writing RabbitMQ Listeners.

Expressive HTTP RabbitMQ middleware for node.js to make web applications and APIs Rabbit Listeners more enjoyable to write. Koa's StackRabbit's middleware stack flows in a stack-like manner, allowing you to perform actions downstream then filter and manipulate the response upstream. Koa's StackRabbit's use of generators also greatly increases the readability and robustness of your application.

Installation

npm install stackrabbit

Getting Started

const stackrabbit = require('stackrabbit')
const contentParser = require('stackrabbit-content-parser')
 
const listener = stackrabbit({
  queueName: 'some-queue',
  hosts: ['rabbit.dev'],
  username: 'guest',
  password: 'guest'
})
 
// You can write middleware just like in Koa
listener.use(function *(next){
  const start = new Date()
  yield next
  const ms = new Date() - start
  console.log('message processed in %s', ms)
})
 
// Use some more middleware
listener.use(contentParser())
 
listener.listen(function * () {
  // do something with the message.
  // this.content is available when using the contentParser middleware
  console.log(this.content)
 
  // make sure to acknowledge you processed the message
  this.app.channel.ack(this.message)
})
 
listener.on('error', (err) => {
  console.error(err.stack)
})
 
listener.connect()

Guide

This guide includes suggestions and best practices for using stackrabbit.

Writing Middleware

Middleware in stackrabbit, much like middleware in koa, are simple functions which return a GeneratorFunction and accept another. When the middleware is run by an "upstream" middleware, it must manually yield to the "downstream" middleware.

Here is an example of adding a unique guid to the header of each message and logging before and after the message has been processed.

const uuid = require('node-uuid')
 
listener.use(function * requestId(next) {
  const start = new Date()
  const headers = this.message.properties.headers
 
  headers['x-request-id'] = headers['x-request-id'] || uuid.v4()
 
  console.log('Processing Message: %s', headers['x-request-id'])
 
  yield next
 
  const ms = new Date() - start
  console.log('Message %s Processed in %s ms', headers['x-request-id'], ms)
})
 

Middleware Best Practices

When creating public middleware it's useful to conform to the convention of wrapping the middleware in a function that accepts options, allowing users to extend functionality. Even if your middleware accepts no options, this is still a good idea to keep things uniform.

Here is a requestId middleware that allows changing the header key through configuration.

function requestId(key) {
  key = key || 'x-request-id'
 
  return function * requestId(next){
    const headers = this.message.properties.headers
    headers[key] = headers[key] || uuid.v4()
 
    yield next
  }
}
 
app.use(requestId());
app.use(requestId('some-other-key'));

Named Middleware

Naming your middleware is optional but it helps debugging.

function namedFn() {
  return function * namedFn(next){
    yield next
  }
}

Error Handling

Errors thrown in the middleware stack or message handler with be caught and the application with emit an event of name error. You should listen for this event and log it accordingly.

listener.on('error', (err) => {
  console.error(err.stack)
})

Inside of your middleware you can easily try/catch the downstream middleware to handle the event. Make sure you throw the error when you're done so the errors can be handled by functions earlier in the middleware chain and get caught in the default error handler.

listener.use(function * (next){
  try {
    yield next
  } catch (err) {
    //  do something with the err
    throw err
  }
})

Available Middleware

stackrabbit does not come bundled with any middleware. you'll might want to include some of these packages.

• stackrabbit-request-id
• stackrabbit-content-parser
• stackrabbit-bunyan
• stackrabbit-newrelic

License

MIT