rascal 9.3.0 → 9.4.0

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Change Log
 
+## 9.4.0
+### Added
+- vhost_initialised event
+- publication paused notifications
+- publication.abort
+
+### Updated
+- broker error events now include vhost connection details
+
 ## 9.3.0
 ### Updated
 - [Fixed #78](https://github.com/guidesmiths/rascal/issues/78) by using a baseline config, and only laying connection options via withDefaultConfig

package/README.md

@@ -114,8 +114,8 @@ The reason Rascal nacks the message is because the alternative is to rollback an
 1. Immediately after obtaining a broker instance
 
     ```js
-    broker.on('error', (err) => {
-      console.error('Broker error', err)
+    broker.on('error', (err, { vhost, connectionUrl }) => {
+      console.error('Broker error', err, vhost, connectionUrl)
     })
     ```
 
@@ -195,6 +195,28 @@ The reason Rascal nacks the message is because the alternative is to rollback an
     })
     ```
 
+### Other Broker Events
+
+#### vhost_initialised
+The broker emits the `vhost_initialised` event after recovering from a connection error. An object containing the vhost name and connection url (with obfuscated password) are passed to he event handler. e.g.
+
+```js
+broker.on('vhost_initialised', ({ vhost, connectionUrl }) => {
+  console.log(`Vhost: ${vhost} was initialised using connection: ${connectionUrl}`);
+})
+```
+
+#### blocked / unblocked
+RabbitMQ notifies clients of [blocked and unblocked](https://www.rabbitmq.com/connection-blocked.html) connections, which rascal forwards from the connection to the broker. e.g.
+```js
+broker.on('blocked', (reason, { vhost, connectionUrl }) => {
+  console.log(`Vhost: ${vhost} was blocked using connection: ${connectionUrl}. Reason: ${reason}`);
+})
+broker.on('unblocked', ({ vhost, connectionUrl }) => {
+  console.log(`Vhost: ${vhost} was unblocked using connection: ${connectionUrl}.`);
+})
+```
+
 ## Configuration
 Rascal is highly configurable, but ships with what we consider to be sensible defaults (optimised for reliability rather than speed) for production and test environments.
 
@@ -766,7 +788,7 @@ try {
     console.log("Message id was: ", messageId)
   }).on("error", (err, messageId) => {
      console.error("Error was: ", err.message)
-  }).on("return", (messageId) => {
+  }).on("return", (message) => {
      console.warn("Message was returned: ", message.properties.messageId)
   })
 } catch (err) {
@@ -817,6 +839,39 @@ When you publish a message using a confirm channel, amqplib will wait for an ack
 }
 ```
 
+#### Aborting
+Rascal uses a channel pool to publish messages. Access to the channel pool is synchronised via an in memory queue, which will be paused if the connection to the broker is temporarily lost. Consequently instead of erroring, publishes will be held until the connection is re-established. If you would rather abort under these circumstances, you can listen for the publication 'paused' event, and call `publication.abort()`. When the connection is re-established any aborted messages will be dropped instead of published.
+
+```js
+broker.publish("p1", "some message", (err, publication) => {
+  if (err) throw err; // publication didn't exist
+  publication.on("success", (messageId) => {
+     console.log("Message id was: ", messageId)
+  }).on("error", (err, messageId) => {
+     console.error("Error was: ", err.message)
+  }).on("paused", (messageId) => {
+     console.warn("Publication was paused. Aborting message: ", messageId)
+     publication.abort();
+  })
+})
+```
+
+```js
+try {
+  const publication = await broker.publish("p1", "some message")
+  publication.on("success", (messageId) => {
+    console.log("Message id was: ", messageId)
+  }).on("error", (err, messageId) => {
+     console.error("Error was: ", err.message)
+  }).on("paused", (messageId) => {
+     console.warn("Publication was paused. Aborting message: ", messageId)
+     publication.abort();
+  })
+} catch (err) {
+  // publication didn't exist
+}
+```
+
 #### Encrypting messages
 Rascal can be configured to automatically encrypt outbound messages.
 ```json

package/lib/amqp/Publication.js

@@ -2,8 +2,8 @@ var debug = require('debug')('rascal:Publication');
 var format = require('util').format;
 var _ = require('lodash');
 var uuid = require('uuid').v4;
-var EventEmitter = require('events').EventEmitter;
 var crypto = require('crypto');
+var PublicationSession = require('./PublicationSession');
 var setTimeoutUnref = require('../utils/setTimeoutUnref');
 
 module.exports = {
@@ -30,7 +30,7 @@ function Publication(vhost, borrowChannelFn, returnChannelFn, destroyChannelFn,
 
   this.init = function(next) {
     debug('Initialising publication: %s', config.name);
-    return next(null, self);
+    next(null, self);
   };
 
   this.publish = function(payload, overrides, next) {
@@ -39,7 +39,7 @@ function Publication(vhost, borrowChannelFn, returnChannelFn, destroyChannelFn,
     publishConfig.options.contentType = publishConfig.options.contentType || content.type;
     publishConfig.options.messageId = publishConfig.options.messageId || uuid();
 
-    return publishConfig.encryption
+    publishConfig.encryption
       ? _publishEncrypted(content.buffer, publishConfig, next)
       : _publish(content.buffer, publishConfig, next);
   };
@@ -87,32 +87,39 @@ function Publication(vhost, borrowChannelFn, returnChannelFn, destroyChannelFn,
   }
 
   function _publish(buffer, publishConfig, next) {
-    var emitter = new EventEmitter();
     var messageId = publishConfig.options.messageId;
+    var session = new PublicationSession(vhost, messageId);
     borrowChannelFn(function(err, channel) {
-      if (err) return emitter.emit('error', err, messageId);
-      var errorHandler = _.once(handleChannelError.bind(null, channel, messageId, emitter, config));
-      var returnHandler = emitter.emit.bind(emitter, 'return');
+      session._removePausedListener();
+      if (err) return session.emit('error', err, messageId);
+      if (session.isAborted()) return abortPublish(channel, messageId);
+      var errorHandler = _.once(handleChannelError.bind(null, channel, messageId, session, config));
+      var returnHandler = session.emit.bind(session, 'return');
       addListeners(channel, errorHandler, returnHandler);
       try {
         publishFn(channel, buffer, publishConfig, function(err, ok) {
           if (err) {
             destroyChannel(channel, errorHandler, returnHandler);
-            return emitter.emit('error', err, messageId);
+            return session.emit('error', err, messageId);
           }
 
           ok ? returnChannel(channel, errorHandler, returnHandler)
              : deferReturnChannel(channel, errorHandler, returnHandler);
 
-          emitter.emit('success', messageId);
+          session.emit('success', messageId);
         });
       } catch(err) {
         returnChannel(channel, errorHandler, returnHandler);
-        return emitter.emit('error', err, messageId);
+        return session.emit('error', err, messageId);
       };
     });
 
-    next(null, emitter);
+    next(null, session);
+  }
+
+  function abortPublish(channel, messageId) {
+    debug('Publication of message: %s was aborted', messageId);
+    returnChannelFn(channel);
   }
 
   function returnChannel(channel, errorHandler, returnHandler) {

package/lib/amqp/PublicationSession.js

@@ -0,0 +1,36 @@
+var debug = require('debug')('rascal:SubscriberSession');
+var EventEmitter = require('events').EventEmitter;
+var inherits = require('util').inherits;
+
+module.exports = PublicationSession;
+
+inherits(PublicationSession, EventEmitter);
+
+function PublicationSession(vhost, messageId) {
+
+  var self = this;
+  var aborted = false;
+
+  this.abort = function() {
+    aborted = true;
+  };
+
+  this.isAborted = function() {
+    return aborted;
+  };
+
+  this._removePausedListener = function() {
+    vhost.removeListener('paused',emitPaused);
+  };
+
+  function emitPaused() {
+    self.emit('paused', messageId);
+  }
+
+  vhost.on('paused', emitPaused);
+
+  self.on('newListener', function(event) {
+    if (event !== 'paused') return;
+    if (vhost.isPaused()) emitPaused();
+  });
+}

package/lib/amqp/Vhost.js

@@ -3,7 +3,6 @@ var format = require('util').format;
 var inherits = require('util').inherits;
 var EventEmitter = require('events').EventEmitter;
 var async = require('async');
-var forwardEvents = require('forward-emitter');
 var genericPool = require('generic-pool');
 var tasks = require('./tasks');
 var uuid = require('uuid').v4;
@@ -33,6 +32,7 @@ function Vhost(config) {
   var purge = async.compose(tasks.closeConnection, tasks.closeChannel, tasks.purgeQueues, tasks.createChannel, tasks.createConnection);
   var nuke = async.compose(tasks.closeConnection, tasks.closeChannel, tasks.deleteQueues, tasks.deleteExchanges, tasks.createChannel, tasks.createConnection);
   var timer = backoff({});
+  var paused = true;
 
   this.name = config.name;
   this.connectionIndex = 0;
@@ -45,22 +45,22 @@ function Vhost(config) {
 
     init(config, { connectionIndex: self.connectionIndex }, function(err, config, ctx) {
       if (err) return next(err);
-      self.emit('connect');
-
-      attachErrorHandlers(ctx.connection, config);
 
-      forwardEvents(ctx.connection, self, function(eventName) {
-        return eventName === 'blocked' || eventName === 'unblocked';
-      });
-      debug('vhost: %s was initialised with connection: %s', self.name, ctx.connection._rascal_id);
       connection = ctx.connection;
       self.connectionIndex = ctx.connectionIndex;
       connectionConfig = ctx.connectionConfig;
       timer = backoff(ctx.connectionConfig.retry);
 
+      attachErrorHandlers(config);
+      forwardRabbitMQConnectionEvents();
       ensureChannelPools();
       resumeChannelAllocation();
 
+      debug('vhost: %s was initialised with connection: %s', self.name, connection._rascal_id);
+
+      self.emit('connect');
+      self.emit('vhost_initialised', getConnectionDetails());
+
       return next(null, self);
     });
     return self;
@@ -162,6 +162,10 @@ function Vhost(config) {
     confirmChannelPool.destroy(channel);
   };
 
+  this.isPaused = function() {
+    return paused;
+  };
+
   function createChannelPool(options) {
     var pool, poolQueue;
     var mode = getChannelMode(options.confirm);
@@ -326,12 +330,25 @@ function Vhost(config) {
     channelCreator.pause();
     regularChannelPool && regularChannelPool.pause();
     confirmChannelPool && confirmChannelPool.pause();
+    paused = true;
+    self.emit('paused', { vhost: self.name });
   }
 
   function resumeChannelAllocation() {
     channelCreator.resume();
     regularChannelPool && regularChannelPool.resume();
     confirmChannelPool && confirmChannelPool.resume();
+    paused = false;
+    self.emit('resumed', { vhost: self.name });
+  }
+
+  function forwardRabbitMQConnectionEvents() {
+    connection.on('blocked', function(reason) {
+      self.emit('blocked', reason, getConnectionDetails());
+    });
+    connection.on('unblocked', function() {
+      self.emit('unblocked', getConnectionDetails());
+    });
   }
 
   function ensureChannelPools() {
@@ -350,7 +367,7 @@ function Vhost(config) {
     ], next);
   }
 
-  function attachErrorHandlers(connection, config) {
+  function attachErrorHandlers(config) {
     connection.removeAllListeners('error');
     var errorHandler = _.once(handleConnectionError.bind(null, connection, config));
     connection.once('error', errorHandler);
@@ -359,10 +376,10 @@ function Vhost(config) {
 
   function handleConnectionError(borked, config, err) {
     debug('Handling connection error: %s initially from connection: %s, %s', err.message, borked._rascal_id, connectionConfig.loggableUrl);
-    self.emit('disconnect');
     pauseChannelAllocation();
     connection = undefined;
-    self.emit('error', err);
+    self.emit('disconnect');
+    self.emit('error', err, getConnectionDetails());
     connectionConfig.retry && self.init(function(err) {
       if (!err) return;
       var delay = timer.next();
@@ -370,4 +387,8 @@ function Vhost(config) {
       setTimeoutUnref(handleConnectionError.bind(null, borked, config, err), delay);
     });
   }
+
+  function getConnectionDetails() {
+    return { vhost: self.name, connectionUrl: connectionConfig.loggableUrl };
+  }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rascal",
-  "version": "9.3.0",
+  "version": "9.4.0",
   "description": "A config driven wrapper for amqplib supporting multi-host connections, automatic error recovery, redelivery flood protection, transparent encryption / decryption,  channel pooling and publication timeouts",
   "main": "index.js",
   "dependencies": {