amqplib 1.0.6 → 1.1.0

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Change log for amqplib
 
+## v1.1.0
+- Add connection recovery via `connectWithRecoveryPromise` and `connectWithRecoveryCallback` — automatically reconnects on connection loss with configurable backoff delay, jitter, and retry limits (thanks [@ShiriNmi1520](https://github.com/ShiriNmi1520))
+
+## v1.0.7
+- Fix `update-secret-ok` event not being forwarded by `ChannelModel` and `CallbackModel` (fixes #849)
+- Add `handler-error` event to connections and channels. If a user-supplied event handler (e.g. `connection.on('close', ...)`, `channel.on('error', ...)`, `channel.on('delivery', ...)` etc.) throws a synchronous error, amqplib will emit a `handler-error` event on the same emitter with the thrown error and the name of the event whose handler threw — provided a `handler-error` listener is registered. If no `handler-error` listener is registered, behaviour is unchanged from previous versions. Note: in previous versions, errors thrown in connection `close` event handlers were silently swallowed; errors thrown in channel event handlers (other than `delivery`/`return`) would kill the channel and possibly the connection (fixes #334).
+
 ## v1.0.6
 - Fix channel.get() not invoking callback with error on channel close; previously only an error event was emitted (fixes #832). **Note:** if you use the callback API, ensure your channel.get() callbacks handle errors — they will now be invoked in error cases where previously they were not. If you use the promise API, the returned promise now rejects with a proper Error object (with .code, .classId and .methodId properties) rather than a raw close frame.
 

package/README.md

@@ -43,10 +43,16 @@ const queue = 'tasks';
 amqplib.connect('amqp://localhost', (err, conn) => {
   if (err) throw err;
 
+  conn.on('error', (err) => { console.error('Connection error:', err); });
+  conn.on('handler-error', (err, event) => { console.error(`Uncaught exception in connection ${event} listener:`, err); });
+
   // Listener
   conn.createChannel((err, ch2) => {
     if (err) throw err;
 
+    ch2.on('error', (err) => { console.error('Channel error:', err); });
+    ch2.on('handler-error', (err, event) => { console.error(`Uncaught exception in channel ${event} listener:`, err); });
+
     ch2.assertQueue(queue);
 
     ch2.consume(queue, (msg) => {
@@ -63,6 +69,8 @@ amqplib.connect('amqp://localhost', (err, conn) => {
   conn.createChannel((err, ch1) => {
     if (err) throw err;
 
+    ch1.on('error', (err) => { console.error('Channel error:', err); });
+    ch1.on('handler-error', (err, event) => { console.error(`Uncaught exception in channel ${event} listener:`, err); });
     ch1.assertQueue(queue);
 
     setInterval(() => {
@@ -80,8 +88,12 @@ const amqplib = require('amqplib');
 (async () => {
   const queue = 'tasks';
   const conn = await amqplib.connect('amqp://localhost');
+  conn.on('error', (err) => { console.error('Connection error:', err); });
+  conn.on('handler-error', (err, event) => { console.error(`Uncaught exception in connection ${event} listener:`, err); });
 
   const ch1 = await conn.createChannel();
+  ch1.on('error', (err) => { console.error('Channel error:', err); });
+  ch1.on('handler-error', (err, event) => { console.error(`Uncaught exception in channel ${event} listener:`, err); });
   await ch1.assertQueue(queue);
 
   // Listener
@@ -96,6 +108,8 @@ const amqplib = require('amqplib');
 
   // Sender
   const ch2 = await conn.createChannel();
+  ch2.on('error', (err) => { console.error('Channel error:', err); });
+  ch2.on('handler-error', (err, event) => { console.error(`Uncaught exception in channel ${event} listener:`, err); });
 
   setInterval(() => {
     ch2.sendToQueue(queue, Buffer.from('something to do'));
@@ -104,6 +118,103 @@ const amqplib = require('amqplib');
 
 ```
 
+## Opt-in recovery
+
+Automatic recovery is available as an opt-in feature through `connect` options:
+
+```javascript
+const amqplib = require('amqplib');
+
+const connection = await amqplib.connect('amqp://localhost', {
+  recovery: {
+    initialDelay: 200, // ms
+    maxDelay: 5000, // ms
+    factor: 2,
+    jitter: 0.2,
+    maxRetries: Infinity,
+    async setup(model) {
+      // Called after every successful (re)connect.
+      // Recreate topology/consumers here.
+      const ch = await model.createChannel();
+      await ch.assertQueue('tasks', {durable: true});
+    },
+  },
+});
+
+connection.on('connect', () => {
+  console.log('connected');
+});
+
+connection.on('disconnect', (err) => {
+  console.warn('disconnected', err.message);
+});
+```
+
+Callback API supports the same option:
+
+```javascript
+const amqplib = require('amqplib/callback_api');
+
+amqplib.connect(
+  'amqp://localhost',
+  {
+    recovery: {
+      initialDelay: 200,
+      maxDelay: 5000,
+      setup(model, done) {
+        model.createChannel((err, ch) => {
+          if (err) return done(err);
+          ch.assertQueue('tasks', {durable: true}, done);
+        });
+      },
+    },
+  },
+  (err, conn) => {
+    if (err) throw err;
+    conn.on('connect', () => console.log('connected'));
+  },
+);
+```
+
+Without `recovery` options, behavior is unchanged.
+
+## Error handling in event handlers
+
+If a user-supplied event handler throws a synchronous error, the throw will
+propagate into amqplib internals. Depending on where in the call stack it
+escapes, this can silently swallow the error, or close the channel or
+connection.
+
+To avoid this, register a `handler-error` listener on the connection and on
+each channel. If a listener is present, amqplib will catch any throw from a
+user event handler and deliver it there instead of letting it propagate
+internally. The listener receives the thrown error and the name of the event
+whose handler threw.
+
+Note that `handler-error` is not a replacement for the `error` event.
+The `error` event is emitted by amqplib itself when the connection or channel
+encounters a protocol-level error. The `handler-error` event is only emitted
+when *your own* event listener throws.
+
+```js
+const connection = await amqp.connect('amqp://localhost');
+
+connection.on('error', (err) => { /* handle protocol errors */ });
+connection.on('handler-error', (err, event) => {
+  console.error(`Uncaught exception in connection ${event} listener:`, err);
+});
+
+const channel = await connection.createChannel();
+
+channel.on('error', (err) => { /* handle protocol errors */ });
+channel.on('handler-error', (err, event) => {
+  console.error(`Uncaught exception in channel ${event} listener:`, err);
+});
+```
+
+If no `handler-error` listener is registered, behaviour is unchanged from
+previous versions.
+
 ## Running tests
 
     npm test

package/callback_api.js

@@ -1,5 +1,6 @@
 const raw_connect = require('./lib/connect').connect;
 const CallbackModel = require('./lib/callback_model').CallbackModel;
+const recovery = require('./lib/recovery');
 
 // Supports three shapes:
 // connect(url, options, callback)
@@ -15,7 +16,21 @@ function connect(url, options, cb) {
     options = false;
   }
 
-  raw_connect(url, options, (err, c) => {
+  const {connectionOptions, recovery: recoveryOptions} = recovery.splitConnectionOptions(options);
+  if (recovery.recoveryEnabled(recoveryOptions)) {
+    const openModel = () => {
+      return new Promise((resolve, reject) => {
+        raw_connect(url, connectionOptions, (err, c) => {
+          if (err === null) resolve(new CallbackModel(c));
+          else reject(err);
+        });
+      });
+    };
+
+    return recovery.connectWithRecoveryCallback(openModel, recoveryOptions, cb);
+  }
+
+  raw_connect(url, connectionOptions, (err, c) => {
     if (err === null) cb(null, new CallbackModel(c));
     else cb(err);
   });

package/channel_api.js

@@ -1,9 +1,17 @@
 const raw_connect = require('./lib/connect').connect;
 const ChannelModel = require('./lib/channel_model').ChannelModel;
 const promisify = require('node:util').promisify;
+const recovery = require('./lib/recovery');
 
 function connect(url, connOptions) {
-  return promisify((cb) => raw_connect(url, connOptions, cb))().then((conn) => new ChannelModel(conn));
+  const {connectionOptions, recovery: recoveryOptions} = recovery.splitConnectionOptions(connOptions);
+  if (recovery.recoveryEnabled(recoveryOptions)) {
+    const openModel = () => promisify((cb) => raw_connect(url, connectionOptions, cb))().then((conn) => new ChannelModel(conn));
+
+    return recovery.connectWithRecoveryPromise(openModel, recoveryOptions);
+  }
+
+  return promisify((cb) => raw_connect(url, connectionOptions, cb))().then((conn) => new ChannelModel(conn));
 }
 
 module.exports.connect = connect;

package/lib/callback_model.js

@@ -7,7 +7,7 @@ class CallbackModel extends EventEmitter {
   constructor(connection) {
     super();
     this.connection = connection;
-    ['error', 'close', 'blocked', 'unblocked'].forEach((ev) => {
+    ['error', 'close', 'blocked', 'unblocked', 'update-secret-ok'].forEach((ev) => {
       connection.on(ev, this.emit.bind(this, ev));
     });
   }

package/lib/channel.js

@@ -7,6 +7,7 @@ const EventEmitter = require('node:events');
 const fmt = require('node:util').format;
 const IllegalOperationError = require('./error').IllegalOperationError;
 const stackCapture = require('./error').stackCapture;
+const safeEmit = require('./safe_emit');
 
 class Channel extends EventEmitter {
   constructor(connection) {
@@ -128,7 +129,7 @@ class Channel extends EventEmitter {
     invalidateSend(this, 'Channel closed', capturedStack);
     this.accept = invalidOp('Channel closed', capturedStack);
     this.connection.releaseChannel(this.ch);
-    this.emit('close');
+    safeEmit(this, 'close');
   }
 
   // Stop being able to send and receive methods and content. Used when
@@ -188,7 +189,7 @@ class Channel extends EventEmitter {
         error.classId = defs.info(id).classId;
         error.methodId = defs.info(id).methodId;
       }
-      this.emit('error', error);
+      safeEmit(this, 'error', error);
     });
   }
 
@@ -250,7 +251,7 @@ class Channel extends EventEmitter {
   }
 
   onBufferDrain() {
-    this.emit('drain');
+    safeEmit(this, 'drain');
   }
 
   accept(f) {
@@ -264,12 +265,12 @@ class Channel extends EventEmitter {
 
       // confirmations, need to do confirm.select first
       case defs.BasicAck:
-        return this.emit('ack', f.fields);
+        return safeEmit(this, 'ack', f.fields);
       case defs.BasicNack:
-        return this.emit('nack', f.fields);
+        return safeEmit(this, 'nack', f.fields);
       case defs.BasicCancel:
         // The broker can send this if e.g., the queue is deleted.
-        return this.emit('cancel', f.fields);
+        return safeEmit(this, 'cancel', f.fields);
 
       case defs.ChannelClose: {
         // Any remote closure is an error to us. Reject the pending reply
@@ -287,7 +288,7 @@ class Channel extends EventEmitter {
         error.code = f.fields.replyCode;
         error.classId = f.fields.classId;
         error.methodId = f.fields.methodId;
-        this.emit('error', error);
+        safeEmit(this, 'error', error);
 
         const s = stackCapture(emsg);
         this.toClosed(s);
@@ -352,7 +353,7 @@ function acceptDeliveryOrReturn(f) {
   const fields = f.fields;
   return acceptMessage((message) => {
     message.fields = fields;
-    this.emit(event, message);
+    safeEmit(this, event, message);
   });
 }
 

package/lib/channel_model.js

@@ -10,7 +10,7 @@ class ChannelModel extends EventEmitter {
     super();
     this.connection = connection;
 
-    ['error', 'close', 'blocked', 'unblocked'].forEach((ev) => {
+    ['error', 'close', 'blocked', 'unblocked', 'update-secret-ok'].forEach((ev) => {
       connection.on(ev, this.emit.bind(this, ev));
     });
   }

package/lib/connection.js

@@ -17,6 +17,7 @@ const fmt = require('node:util').format;
 const PassThrough = require('node:stream').PassThrough;
 const IllegalOperationError = require('./error').IllegalOperationError;
 const stackCapture = require('./error').stackCapture;
+const safeEmit = require('./safe_emit');
 
 // High-water mark for channel write buffers, in 'objects' (which are
 // encoded frames as buffers).
@@ -281,7 +282,7 @@ class Connection extends EventEmitter {
   }
 
   closeWithError(reason, code, error) {
-    this.emit('error', error);
+    safeEmit(this, 'error', error);
     this.closeBecause(reason, code);
   }
 
@@ -290,7 +291,7 @@ class Connection extends EventEmitter {
       // forestall any more calls to onSocketError, since we're signed
       // up for `'error'` *and* `'end'`
       this.expectSocketClose = true;
-      this.emit('error', err);
+      safeEmit(this, 'error', err);
       const s = stackCapture('Socket error');
       this.toClosed(s, err);
     }
@@ -345,7 +346,7 @@ class Connection extends EventEmitter {
     // This is certainly true now, if it wasn't before
     this.expectSocketClose = true;
     this.stream.end();
-    this.emit('close', maybeErr);
+    safeEmit(this, 'close', maybeErr);
   }
 
   _updateSecret(newSecret, reason, cb) {
@@ -363,7 +364,7 @@ class Connection extends EventEmitter {
       const hb = new Heart(this.heartbeat, this.checkSend.bind(this), this.checkRecv.bind(this));
       hb.on('timeout', () => {
         const hberr = new Error('Heartbeat timeout');
-        this.emit('error', hberr);
+        safeEmit(this, 'error', hberr);
         const s = stackCapture('Heartbeat timeout');
         this.toClosed(s, hberr);
       });
@@ -585,17 +586,17 @@ function channel0(connection) {
       const e = new Error(emsg);
       e.code = f.fields.replyCode;
       if (isFatalError(e)) {
-        connection.emit('error', e);
+        safeEmit(connection, 'error', e);
       }
       connection.toClosed(s, e);
     } else if (f.id === defs.ConnectionBlocked) {
       connection.blocked = true;
-      connection.emit('blocked', f.fields.reason);
+      safeEmit(connection, 'blocked', f.fields.reason);
     } else if (f.id === defs.ConnectionUnblocked) {
       connection.blocked = false;
-      connection.emit('unblocked');
+      safeEmit(connection, 'unblocked');
     } else if (f.id === defs.ConnectionUpdateSecretOk) {
-      connection.emit('update-secret-ok');
+      safeEmit(connection, 'update-secret-ok');
     } else {
       connection.closeWithError(
         fmt('Unexpected frame on channel 0'),