microservice-kit v0.9.1

microservice-kit

Utility belt for building microservices.

Quick Start

• Check out /demo folder
• A boilerplate for your new microservice

API Reference

Class MicroserviceKit

This is the main class, the entry point to microservice-kit. To use it, you just need to import microservice-kit:

const MicroserviceKit = require('microservice-kit');

To create an instance, look at constructor below. A microservice-kit instance is simply collection of an AmqpKit and a ShutdownKit instances.

new MicroserviceKit(options={})

Params

Sample

const microserviceKit = new MicroserviceKit({
    type: 'core-worker',
    amqp: {
        url: "amqp://localhost",
        queues: [
            {
                name: "core",
                options: {durable: true}
            }
        ],
        exchanges: []
    }
});

MicroserviceKit.prototype.amqpKit

This amqpKit instance is automatically created for microservice. See AmqpKit for details.

const coreQueue = microserviceKit.amqpKit.getQueue('core');

MicroserviceKit.prototype.shutdownKit

This shutdownKit (singleton) instance is automatically created for microservice. See ShutdownKit for details.

microserviceKit.shutdownKit.addJob(someFunction);

MicroserviceKit.prototype.init() -> Promise

Created instance is not ready yet, it will connect to rabbitmq. You should call this method when booting your app.

microserviceKit
  .init()
  .then(() => {
    console.log("Initalized microservicekit!");
  })
  .catch((err) => {
    console.log("Cannot initalize microservicekit!", err);
  })

MicroserviceKit.prototype.getName() -> String

This is the unique name of the created instance. It begins with microservice type and followed by random string. Ex: socket-worker-54a98630

Class AmqpKit

This is the AmqpKit class aims to help communication over RabbitMQ. Main features:

• Get callbacks like natively instead of low-level RabbitMQ RPC topologies
• Send & recieve events instead of messages. Events are just special message hierarchy.
• Send & recieve payloads in native JSON format instead of buffers.
• Progress support, a consumer can inform its progress to the producer.

AmqpKit uses amqplib in barebones. Look at its documentation. We will refer this page a lot.

const AmqpKit = require('microservice-kit').AmqpKit;

You can reach AmqpKit class like above. However, if you create a MicroserviceKit instance you don't need to reach AmqpKit. An AmqpKit instance will be automatically created for you.

new AmqpKit([options={}])

Only use this constructor for advanced usage! An AmqpKit instance will be automatically created, if you use new MicroserviceKit(options) constructor. If so, options.amqp will be used while creating AmqpKit instance.

Params

Sample

const amqpKit = new AmqpKit({
  queues: [
      {
          key: 'broadcast',
          options: {exclusive: true}
      },
      {
          key: 'direct',
          options: {exclusive: true}
      }
  ],
  exchanges: [
      {
          name: 'socket-broadcast',
          key: 'socket-broadcast',
          type: 'fanout',
          options: {}
      },
      {
          name: 'socket-direct',
          key: 'socket-direct',
          type: 'direct',
          options: {}
      }
  ],
  logger: function() {
      var args = Array.prototype.slice.call(arguments);
      args.unshift('[amqpkit]');
      console.log.apply(console, args);
  }
});

AmqpKit.prototype.prefetch(count, [global])

AmqpKit has two channels by default. The common channel, is used for recieving and sending messages in your microservice. Another channel is for getting rpc callbacks and used exclusively inside AmqpKit. This method sets a limit the number of unacknowledged messages on the common channel. If this limit is reached, RabbitMQ won't send any events to microservice.

Params

Sample

microserviceKit.amqpKit.prefetch(100, true);

This microservice can process maximum 100 events at the same time. (Event type does not matter) RabbitMQ won't send any message to the microservice until it completes some jobs.

AmqpKit.prototype.getQueue(key) -> AmqpKit.Queue

Gets queue instance by key.

AmqpKit.prototype.getExchange(key) -> AmqpKit.Exchange

Gets exchange instance by key.

AmqpKit.prototype.createQueue(key, name, options={}) -> Promise.<AmqpKit.Queue>

Creates (assert) a queue.

AmqpKit.prototype.createExchange(key, name, type, options={}) -> Promise.<AmqpKit.Exchange>

Creates (asserts) an exchange.

AmqpKit.prototype.connection

Native ampqlibs connection. See offical docs.

AmqpKit.prototype.channel

Native ampqlibs channel instance that will be used commonly. See offical docs.

Class AmqpKit.Queue

This class is not exposed to user. When you do amqpKit.getQueue() or amqpKit.createQueue(), what you get is an instance of this class.

AmqpKit.Queue.prototype.consumeEvent(eventName, callback, [options={}])

Sends an event to queue.

Params

Sample

const coreQueue = microserviceKit.amqpKit.getQueue('core');

coreQueue.consumeEvent('get-device', (payload, done, progress) => {
  // Optional progress events!
  let count = 0;
  let interval = setInterval(() => {
      progress({data: 'Progress ' + (++count) + '/5'});
  }, 1000);

  // complete job.
  setTimeout(() => {
      clearInterval(interval);
      done(null, {some: 'Response!'});
  }, 5000);
}, {});

AmqpKit.Queue.prototype.bind(exhange, pattern) -> Promise

Assert a routing pattern from an exchange to the queue: the exchange named by source will relay messages to the queue named, according to the type of the exchange and the pattern given.

Params

AmqpKit.Queue.prototype.unbind(exchange, pattern) -> Promise

Remove a routing path between the queue named and the exchange named as source with the pattern and arguments given.

AmqpKit.Queue.prototype.getUniqueName() -> String

Returns real queue name on RabbitMQ.

AmqpKit.Queue.prototype.sendEvent(eventName, [payload={}], [options={}]) -> Promise

Sends an event with payload to the queue.

Params

Sample

const coreQueue = microserviceKit.amqpKit.getQueue('core');

coreQueue
  .sendEvent('get-device', {id: 5}, {persistent: true})
  .progress((payload) => {
    console.log('The job is processing...', payload);
  })
  .success((payload) => {
    console.log('Device: ', payload);
  })
  .catch((err) => {
    console.log('Cannot get device', err);
  })

Notice the .progress() handler? It's just a additonal handler that AmqpKit puts for you. Instead of this, return value of this method is Promise.

Class AmqpKit.Exchange

This class is not exposed to user. When you do amqpKit.getExchange() or amqpKit.createExchange(), what you get is an instance of this class.

AmqpKit.Exchange.prototype.publishEvent(routingKey, eventName, [payload], [options]) -> Promise

Sends an event with payload to the exchange.

Params

Sample

const broadcastExchange = microserviceKit.amqpKit.getExchange('socket-broadcast');
broadcastExchange.publishEvent('', 'channel-updated', {channel: 'data'}, {dontExpectRpc: true});

Class ShutdownKit

This class helps us to catch interrupt signals, uncaught exceptions and tries to perform jobs to shutdown gracefully. This class is singleton.

// Direct access
const shutdownKit = require('microservice-kit').ShutdownKit;

// Or from microservice-kit instance
const microserviceKit = new MicroserviceKit({...});
console.log(microserviceKit.shutdownKit);

As you can see above, you can access ShutdownKit singleton instance in multiple ways.

ShutdownKit.prototype.addJob(job)

Add a job to graceful shutdown process. When ShutdownKit tries to shutdown gracefully, it runs all the jobs in parallel.

Params

Sample

shutdownKit.addJob((done) => {
    debug('Closing connection...');
    this.connection
      .close()
      .then(() => {
          done();
      })
      .catch(done);
});

ShutdownKit.prototype.gracefulShutdown()

This method gracefully shutdowns current node process.

ShutdownKit.prototype.setLogger(logger)

Sets a custom logger to print out shutdown process logs to console.

Params

Sample

shutdownKit.setLogger(() => {
  var args = Array.prototype.slice.call(arguments);
  args.unshift('[shutdownkit]');
  console.log.apply(console, args);
});

As you can see, we convert all arguments to native array and prepends [shutdown] prefix. Then apply this arguments to standart console.log method.