amqplib 1.0.5 → 1.0.7

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Change log for amqplib
 
+## 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.
+
 ## v1.0.5
 - Fix ConfirmChannel callbacks silently dropped on channel close when some publishes had no callback (fixes #191)
 

package/Makefile

@@ -2,7 +2,7 @@ RABBITMQ_SRC_VERSION=v3.12.13
 JSON=amqp-rabbitmq-0.9.1.json
 AMQP_JSON=https://raw.githubusercontent.com/rabbitmq/rabbitmq-server/$(RABBITMQ_SRC_VERSION)/deps/rabbitmq_codegen/$(JSON)
 
-NODEJS_VERSIONS='18.13.0' '20.10.0' '22.14.0' '24.7.0'
+NODEJS_VERSIONS='18.20.0' '20.10.0' '22.14.0' '24.7.0'
 
 UGLIFY=./node_modules/.bin/uglifyjs
 

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,43 @@ const amqplib = require('amqplib');
 
 ```
 
+## 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/lib/callback_model.js

@@ -1,14 +1,13 @@
 const defs = require('./defs');
 const EventEmitter = require('node:events');
-const BaseChannel = require('./channel').BaseChannel;
-const acceptMessage = require('./channel').acceptMessage;
 const Args = require('./api_args');
+const { BaseChannel, acceptMessage, convertCloseFrameToError } = require('./channel');
 
 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));
     });
   }
@@ -179,17 +178,17 @@ class Channel extends BaseChannel {
     const fields = Args.get(queue, options);
     const cb = callbackWrapper(this, cb0);
     this.sendOrEnqueue(defs.BasicGet, fields, (err, f) => {
-      if (err === null) {
-        if (f.id === defs.BasicGetEmpty) {
-          cb(null, false);
-        } else if (f.id === defs.BasicGetOk) {
-          this.handleMessage = acceptMessage((m) => {
-            m.fields = f.fields;
-            cb(null, m);
-          });
-        } else {
-          cb(new Error(`Unexpected response to BasicGet: ${inspect(f)}`));
-        }
+      if (err instanceof Error) return cb(err);
+      if (err) return cb(convertCloseFrameToError(defs.BasicGet, err));
+      if (f.id === defs.BasicGetEmpty) {
+        cb(null, false);
+      } else if (f.id === defs.BasicGetOk) {
+        this.handleMessage = acceptMessage((m) => {
+          m.fields = f.fields;
+          cb(null, m);
+        });
+      } else {
+        cb(new Error(`Unexpected response to BasicGet: ${inspect(f)}`));
       }
     });
     return this;

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) {
@@ -116,19 +117,7 @@ class Channel extends EventEmitter {
       else if (err instanceof Error) return cb(err);
       // A close frame will be given if this is the RPC awaiting reply
       // and the channel is closed by the server
-      else {
-        // otherwise, it's a close frame
-        const closeReason = (err.fields.classId << 16) + err.fields.methodId;
-        const e =
-          method === closeReason
-            ? fmt('Operation failed: %s; %s', methodName(method), closeMsg(err))
-            : fmt('Channel closed by server: %s', closeMsg(err));
-        const closeFrameError = new Error(e);
-        closeFrameError.code = err.fields.replyCode;
-        closeFrameError.classId = err.fields.classId;
-        closeFrameError.methodId = err.fields.methodId;
-        return cb(closeFrameError);
-      }
+      else return cb(convertCloseFrameToError(method, err));
     }
 
     this.sendOrEnqueue(method, fields, reply);
@@ -140,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
@@ -200,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);
     });
   }
 
@@ -262,7 +251,7 @@ class Channel extends EventEmitter {
   }
 
   onBufferDrain() {
-    this.emit('drain');
+    safeEmit(this, 'drain');
   }
 
   accept(f) {
@@ -276,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
@@ -299,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);
@@ -364,7 +353,7 @@ function acceptDeliveryOrReturn(f) {
   const fields = f.fields;
   return acceptMessage((message) => {
     message.fields = fields;
-    this.emit(event, message);
+    safeEmit(this, event, message);
   });
 }
 
@@ -428,6 +417,19 @@ function acceptMessage(continuation) {
   }
 }
 
+function convertCloseFrameToError(method, closeFrame) {
+  const closeReason = (closeFrame.fields.classId << 16) + closeFrame.fields.methodId;
+  const e =
+    method === closeReason
+      ? fmt('Operation failed: %s; %s', methodName(method), closeMsg(closeFrame))
+      : fmt('Channel closed by server: %s', closeMsg(closeFrame));
+  const error = new Error(e);
+  error.code = closeFrame.fields.replyCode;
+  error.classId = closeFrame.fields.classId;
+  error.methodId = closeFrame.fields.methodId;
+  return error;
+}
+
 // This adds just a bit more stuff useful for the APIs, but not
 // low-level machinery.
 class BaseChannel extends Channel {
@@ -471,3 +473,4 @@ class BaseChannel extends Channel {
 module.exports.acceptMessage = acceptMessage;
 module.exports.BaseChannel = BaseChannel;
 module.exports.Channel = Channel;
+module.exports.convertCloseFrameToError = convertCloseFrameToError;

package/lib/channel_model.js

@@ -1,9 +1,8 @@
 const EventEmitter = require('node:events');
-const promisify = require('node:util').promisify;
+const { promisify } = require('node:util');
 const defs = require('./defs');
-const { BaseChannel } = require('./channel');
-const { acceptMessage } = require('./channel');
 const Args = require('./api_args');
+const { BaseChannel, acceptMessage, convertCloseFrameToError } = require('./channel');
 const { inspect } = require('./format');
 
 class ChannelModel extends EventEmitter {
@@ -11,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));
     });
   }
@@ -159,7 +158,8 @@ class Channel extends BaseChannel {
     const fields = Args.get(queue, options);
     return new Promise((resolve, reject) => {
       this.sendOrEnqueue(defs.BasicGet, fields, (err, f) => {
-        if (err) return reject(err);
+        if (err instanceof Error) return reject(err);
+        if (err) return reject(convertCloseFrameToError(defs.BasicGet, err));
         if (f.id === defs.BasicGetEmpty) {
           return resolve(false);
         } else if (f.id === defs.BasicGetOk) {

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'),

package/lib/safe_emit.js

@@ -0,0 +1,13 @@
+function safeEmit(emitter, event, ...args) {
+  try {
+    emitter.emit(event, ...args);
+  } catch (e) {
+    if (emitter.listenerCount('handler-error') > 0) {
+      setImmediate(() => emitter.emit('handler-error', e, event));
+    } else {
+      throw e;
+    }
+  }
+}
+
+module.exports = safeEmit;

package/package.json

@@ -2,7 +2,7 @@
   "name": "amqplib",
   "homepage": "http://amqp-node.github.io/amqplib/",
   "main": "./channel_api.js",
-  "version": "1.0.5",
+  "version": "1.0.7",
   "description": "An AMQP 0-9-1 (e.g., RabbitMQ) library and client.",
   "repository": {
     "type": "git",

package/test/callback_api.test.js

@@ -42,6 +42,17 @@ describe('Callback API', () => {
         });
       });
     });
+
+    it('emits update-secret-ok event', (_t, done) => {
+      connect((err, _c) => {
+        assert.ifError(err);
+        c = _c;
+        c.on('update-secret-ok', () => done());
+        c.updateSecret(Buffer.from('new secret'), 'no reason', (err) => {
+          assert.ifError(err);
+        });
+      });
+    });
   });
 
   const channel_test_fn = (method) => {
@@ -401,39 +412,18 @@ describe('Callback API', () => {
       });
     });
 
-    /*
-    When this test was refactored as part of the move to the node test framework
-    it failed because only the domain error handler was ever invoked and not the
-    channel.get error callback.
-
-    The original test passed because twice.first (refactored to use util.latch) short circuits on error rather
-    than waiting for twice.second to be invoked. I have verified that the pre-refactored
-    amqplib does not invoke the channel.get callback when the queue does not exist.
-    See lib/callback_model.js
-    */
     error_test('Get from non-queue invokes error', (ch, done, dom) => {
       const decrementLatch = latch(2, () => done());
       dom.on('error', (err) => {
         assert.match(err.message, /404 \(NOT-FOUND\)/);
-        decrementLatch(err);
+        decrementLatch();
       });
       ch.get('', {}, (err) => {
         assert.match(err.message, /404 \(NOT-FOUND\)/)
-        decrementLatch(err)
+        decrementLatch()
       });
     });
 
-    /*
-    When this test was refactored as part of the move to the node test framework
-    it failed because only the domain error handler was ever invoked and not the
-    channel.consume error callback. Unlike the above channel.get test,
-    channel.consume does invoke the channel.consume callback with an error, but
-    the original test did not supply one, mistakenly providing a message handler
-    function instead.
-
-    The original test passed because twice.first (refactored to use util.latch) short circuits on error
-    rather than waiting for twice.second to be invoked.
-    */
     error_test('Consume from non-queue invokes error', (ch, done, dom) => {
       const decrementLatch = latch(2, done);
       dom.on('error', (err) => {

package/test/channel.test.js

@@ -1,4 +1,4 @@
-const { describe, it } = require('node:test');
+const { describe, it, beforeEach, afterEach } = require('node:test');
 const assert = require('node:assert');
 const promisify = require('node:util').promisify;
 const Channel = require('../lib/channel').Channel;
@@ -609,4 +609,310 @@ describe('Channel', () => {
       cb();
     }));
   });
+
+  describe('Event handler errors - without handler-error listener', () => {
+    let prevUncaughtExceptionListeners;
+
+    beforeEach(() => {
+      prevUncaughtExceptionListeners = process.rawListeners('uncaughtException').slice();
+      process.removeAllListeners('uncaughtException');
+    });
+
+    afterEach(() => {
+      prevUncaughtExceptionListeners.forEach((h) => process.on('uncaughtException', h));
+    });
+
+    it('throw in close handler kills the connection without handler-error listener', channelTest((ch, cb, conn) => {
+      const expectedErr = new Error('user close handler explodes');
+      let connErrorSeen = false;
+      // The throw propagates to acceptLoop → frameError → onSocketError → connection.emit('error')
+      conn.on('error', (err) => {
+        assert.strictEqual(err, expectedErr);
+        connErrorSeen = true;
+      });
+      // The ChannelCloseOk buffered before the kill is flushed by the mux after the
+      // stream is ended, producing ERR_STREAM_PUSH_AFTER_EOF. Absorb it and use it
+      // as the signal to end the test, since it fires after the conn error.
+      process.once('uncaughtException', (err) => {
+        assert.strictEqual(err.code, 'ERR_STREAM_PUSH_AFTER_EOF');
+        assert.ok(connErrorSeen);
+        cb();
+      });
+      ch.once('error', (err) => { assert.match(err.message, /Channel closed by server/); });
+      ch.on('close', () => { throw expectedErr; });
+      open(ch);
+    }, (send, _wait, cb, ch) => {
+      completes(() => {
+        send(defs.ChannelClose, {
+          replyText: 'Forced close',
+          replyCode: defs.constants.CHANNEL_ERROR,
+          classId: 0,
+          methodId: 0,
+        }, ch);
+      }, cb);
+    }));
+
+    it('throw in error handler becomes uncaught exception', channelTest((ch, cb) => {
+      const expectedErr = new Error('user error handler explodes');
+      process.once('uncaughtException', (err) => {
+        assert.strictEqual(err, expectedErr);
+        cb();
+      });
+      ch.on('error', () => { throw expectedErr; });
+      open(ch);
+    }, (send, wait, cb, ch) => {
+      send(defs.ChannelClose, {
+        replyText: 'Forced close',
+        replyCode: defs.constants.CHANNEL_ERROR,
+        classId: 0,
+        methodId: 0,
+      }, ch);
+      wait(defs.ChannelCloseOk)().then(cb, cb);
+    }));
+
+    it('throw in drain handler becomes uncaught exception', channelTest((ch, cb) => {
+      const expectedErr = new Error('user drain handler explodes');
+      process.once('uncaughtException', (err) => {
+        assert.strictEqual(err, expectedErr);
+        cb();
+      });
+      ch.on('drain', () => { throw expectedErr; });
+      // Call outside a Promise chain so the throw becomes an uncaughtException
+      open(ch).then(() => setImmediate(() => ch.onBufferDrain()));
+    }, (_send, _wait, cb) => { cb(); }));
+
+    it('throw in ack handler becomes uncaught exception', channelTest((ch, cb) => {
+      const expectedErr = new Error('user ack handler explodes');
+      process.once('uncaughtException', (err) => {
+        assert.strictEqual(err, expectedErr);
+        cb();
+      });
+      ch.on('ack', () => { throw expectedErr; });
+      open(ch);
+    }, (send, _wait, cb, ch) => {
+      completes(() => {
+        send(defs.BasicAck, { deliveryTag: 1, multiple: false }, ch);
+      }, cb);
+    }));
+
+    it('throw in nack handler becomes uncaught exception', channelTest((ch, cb) => {
+      const expectedErr = new Error('user nack handler explodes');
+      process.once('uncaughtException', (err) => {
+        assert.strictEqual(err, expectedErr);
+        cb();
+      });
+      ch.on('nack', () => { throw expectedErr; });
+      open(ch);
+    }, (send, _wait, cb, ch) => {
+      completes(() => {
+        send(defs.BasicNack, { deliveryTag: 1, multiple: false, requeue: false }, ch);
+      }, cb);
+    }));
+
+    it('throw in cancel handler becomes uncaught exception', channelTest((ch, cb) => {
+      const expectedErr = new Error('user cancel handler explodes');
+      process.once('uncaughtException', (err) => {
+        assert.strictEqual(err, expectedErr);
+        cb();
+      });
+      ch.on('cancel', () => { throw expectedErr; });
+      open(ch);
+    }, (send, _wait, cb, ch) => {
+      completes(() => {
+        send(defs.BasicCancel, { consumerTag: 'tag', nowait: false }, ch);
+      }, cb);
+    }));
+
+    it('throw in delivery handler closes channel with error', channelTest((ch, cb) => {
+      // acceptMessageFrame catches the throw and routes it to closeWithError,
+      // which fires channel 'error' then 'close' — it does NOT become an uncaughtException.
+      const expectedErr = new Error('user delivery handler explodes');
+      const decrementLatch = latch(2, cb);
+      ch.on('error', (err) => {
+        assert.strictEqual(err, expectedErr);
+        decrementLatch();
+      });
+      ch.on('close', decrementLatch);
+      ch.on('delivery', () => { throw expectedErr; });
+      open(ch);
+    }, (send, wait, cb, ch) => {
+      send(defs.BasicDeliver, DELIVER_FIELDS, ch, Buffer.from('hello'));
+      wait(defs.ChannelClose)()
+        .then(() => send(defs.ChannelCloseOk, {}, ch))
+        .then(cb, cb);
+    }));
+
+    it('throw in return handler closes channel with error', channelTest((ch, cb) => {
+      // acceptMessageFrame catches the throw and routes it to closeWithError.
+      const expectedErr = new Error('user return handler explodes');
+      const decrementLatch = latch(2, cb);
+      ch.on('error', (err) => {
+        assert.strictEqual(err, expectedErr);
+        decrementLatch();
+      });
+      ch.on('close', decrementLatch);
+      ch.on('return', () => { throw expectedErr; });
+      open(ch);
+    }, (send, wait, cb, ch) => {
+      send(defs.BasicReturn, DELIVER_FIELDS, ch, Buffer.from('hello'));
+      wait(defs.ChannelClose)()
+        .then(() => send(defs.ChannelCloseOk, {}, ch))
+        .then(cb, cb);
+    }));
+  });
+
+  describe('Event handler errors - with handler-error listener', () => {
+    let prevUncaughtExceptionListeners;
+
+    beforeEach(() => {
+      prevUncaughtExceptionListeners = process.rawListeners('uncaughtException').slice();
+      process.removeAllListeners('uncaughtException');
+    });
+
+    afterEach(() => {
+      prevUncaughtExceptionListeners.forEach((h) => process.on('uncaughtException', h));
+    });
+
+    it('throw in close handler is delivered via handler-error event', channelTest((ch, cb) => {
+      const expectedErr = new Error('user close handler explodes');
+      ch.on('handler-error', (err, event) => {
+        assert.strictEqual(err, expectedErr);
+        assert.strictEqual(event, 'close');
+        cb();
+      });
+      // A server-initiated ChannelClose always fires 'error' before 'close' (line 291 in channel.js).
+      // Handle it so only the throw from the close handler reaches handler-error.
+      ch.once('error', (err) => { assert.match(err.message, /Channel closed by server/); });
+      ch.on('close', () => { throw expectedErr; });
+      open(ch);
+    }, (send, wait, cb, ch) => {
+      send(defs.ChannelClose, {
+        replyText: 'Forced close',
+        replyCode: defs.constants.CHANNEL_ERROR,
+        classId: 0,
+        methodId: 0,
+      }, ch);
+      wait(defs.ChannelCloseOk)().then(cb, cb);
+    }));
+
+    it('throw in error handler is delivered via handler-error event', channelTest((ch, cb) => {
+      const expectedErr = new Error('user error handler explodes');
+      ch.on('handler-error', (err, event) => {
+        assert.strictEqual(err, expectedErr);
+        assert.strictEqual(event, 'error');
+        cb();
+      });
+      ch.on('error', () => { throw expectedErr; });
+      open(ch);
+    }, (send, wait, cb, ch) => {
+      send(defs.ChannelClose, {
+        replyText: 'Forced close',
+        replyCode: defs.constants.CHANNEL_ERROR,
+        classId: 0,
+        methodId: 0,
+      }, ch);
+      wait(defs.ChannelCloseOk)().then(cb, cb);
+    }));
+
+    it('throw in drain handler is delivered via handler-error event', channelTest((ch, cb) => {
+      const expectedErr = new Error('user drain handler explodes');
+      ch.on('handler-error', (err, event) => {
+        assert.strictEqual(err, expectedErr);
+        assert.strictEqual(event, 'drain');
+        cb();
+      });
+      ch.on('drain', () => { throw expectedErr; });
+      open(ch).then(() => setImmediate(() => ch.onBufferDrain()));
+    }, (_send, _wait, cb) => { cb(); }));
+
+    it('throw in ack handler is delivered via handler-error event', channelTest((ch, cb) => {
+      const expectedErr = new Error('user ack handler explodes');
+      ch.on('handler-error', (err, event) => {
+        assert.strictEqual(err, expectedErr);
+        assert.strictEqual(event, 'ack');
+        cb();
+      });
+      ch.on('ack', () => { throw expectedErr; });
+      open(ch);
+    }, (send, _wait, cb, ch) => {
+      completes(() => {
+        send(defs.BasicAck, { deliveryTag: 1, multiple: false }, ch);
+      }, cb);
+    }));
+
+    it('throw in nack handler is delivered via handler-error event', channelTest((ch, cb) => {
+      const expectedErr = new Error('user nack handler explodes');
+      ch.on('handler-error', (err, event) => {
+        assert.strictEqual(err, expectedErr);
+        assert.strictEqual(event, 'nack');
+        cb();
+      });
+      ch.on('nack', () => { throw expectedErr; });
+      open(ch);
+    }, (send, _wait, cb, ch) => {
+      completes(() => {
+        send(defs.BasicNack, { deliveryTag: 1, multiple: false, requeue: false }, ch);
+      }, cb);
+    }));
+
+    it('throw in cancel handler is delivered via handler-error event', channelTest((ch, cb) => {
+      const expectedErr = new Error('user cancel handler explodes');
+      ch.on('handler-error', (err, event) => {
+        assert.strictEqual(err, expectedErr);
+        assert.strictEqual(event, 'cancel');
+        cb();
+      });
+      ch.on('cancel', () => { throw expectedErr; });
+      open(ch);
+    }, (send, _wait, cb, ch) => {
+      completes(() => {
+        send(defs.BasicCancel, { consumerTag: 'tag', nowait: false }, ch);
+      }, cb);
+    }));
+
+    it('throw in delivery handler is delivered via handler-error event', channelTest((ch, cb) => {
+      const expectedErr = new Error('user delivery handler explodes');
+      ch.on('handler-error', (err, event) => {
+        assert.strictEqual(err, expectedErr);
+        assert.strictEqual(event, 'delivery');
+        cb();
+      });
+      ch.on('delivery', () => { throw expectedErr; });
+      open(ch);
+    }, (send, _wait, cb, ch) => {
+      completes(() => {
+        send(defs.BasicDeliver, DELIVER_FIELDS, ch, Buffer.from('hello'));
+      }, cb);
+    }));
+
+    it('throw in return handler is delivered via handler-error event', channelTest((ch, cb) => {
+      const expectedErr = new Error('user return handler explodes');
+      ch.on('handler-error', (err, event) => {
+        assert.strictEqual(err, expectedErr);
+        assert.strictEqual(event, 'return');
+        cb();
+      });
+      ch.on('return', () => { throw expectedErr; });
+      open(ch);
+    }, (send, _wait, cb, ch) => {
+      completes(() => {
+        send(defs.BasicReturn, DELIVER_FIELDS, ch, Buffer.from('hello'));
+      }, cb);
+    }));
+
+    it('throw in handler-error handler becomes uncaught exception', channelTest((ch, cb) => {
+      const expectedErr = new Error('handler-error handler explodes');
+      process.once('uncaughtException', (err) => {
+        assert.strictEqual(err, expectedErr);
+        cb();
+      });
+      ch.on('handler-error', () => { throw expectedErr; });
+      ch.on('ack', () => { throw new Error('user ack handler explodes'); });
+      open(ch);
+    }, (send, _wait, cb, ch) => {
+      completes(() => {
+        send(defs.BasicAck, { deliveryTag: 1, multiple: false }, ch);
+      }, cb);
+    }));
+  });
 });

package/test/channel_api.test.js

@@ -25,6 +25,15 @@ describe('updateSecret', () => {
         .finally(() => c.close())
     );
   });
+
+  it('emits update-secret-ok event', () => {
+    return connect().then((c) =>
+      new Promise((resolve, reject) => {
+        c.on('update-secret-ok', resolve);
+        c.updateSecret(Buffer.from('new secret'), 'no reason').catch(reject);
+      }).finally(() => c.close())
+    );
+  });
 });
 
 describe('assert, check, delete', () => {
@@ -176,6 +185,48 @@ describe('sendMessage', () => {
   });
 });
 
+describe('get', () => {
+  it('returns false when queue is empty', () => {
+    return withChannel((ch) =>
+      ch.assertQueue('test.get-empty', QUEUE_OPTS)
+        .then(() => ch.purgeQueue('test.get-empty'))
+        .then(() => ch.get('test.get-empty', { noAck: true }))
+        .then((m) => assert.strictEqual(false, m))
+    );
+  });
+
+  it('returns a message when queue has messages', () => {
+    const msg = randomString();
+    return withChannel((ch) =>
+      ch.assertQueue('test.get-message', QUEUE_OPTS)
+        .then(() => ch.purgeQueue('test.get-message'))
+        .then(() => {
+          ch.sendToQueue('test.get-message', Buffer.from(msg));
+          return waitForMessages('test.get-message');
+        })
+        .then(() => ch.get('test.get-message', { noAck: true }))
+        .then((m) => {
+          assert(m);
+          assert.equal(msg, m.content.toString());
+        })
+    );
+  });
+
+  it('rejects with a proper error when queue does not exist', () => {
+    return withChannel((ch) => {
+      ch.once('error', ignore);
+      return assert.rejects(() => ch.get('', {}), (err) => {
+        assert(err instanceof Error);
+        assert.match(err.message, /NOT_FOUND/);
+        assert.strictEqual(404, err.code);
+        assert.strictEqual(60, err.classId);
+        assert.strictEqual(70, err.methodId);
+        return true;
+      });
+    });
+  });
+});
+
 describe('binding, consuming', () => {
   // bind, publish, get
   it('route message', () => {

package/test/connection.test.js

@@ -300,6 +300,357 @@ describe('Connection', () => {
     }));
   });
 
+  describe('Event handler errors - without handler-event listener', () => {
+    let prevUncaughtExceptionListeners;
+
+    beforeEach(() => {
+      prevUncaughtExceptionListeners = process.rawListeners('uncaughtException').slice();
+      process.removeAllListeners('uncaughtException');
+    });
+
+    afterEach(() => {
+      prevUncaughtExceptionListeners.forEach((h) => process.on('uncaughtException', h));
+      heartbeat.UNITS_TO_MS = 1000;
+    });
+
+    it('throw in close handler from server-initiated close is swallowed without handler-error listener', connectionTest((c, cb) => {
+      c.on('close', () => { throw new Error('user handler explodes'); });
+      c.open(OPEN_OPTS);
+      cb();
+    }, (send, wait, cb) => {
+      handshake(send, wait)
+        .then(() => send(defs.ConnectionClose, {
+          replyText: 'Begone',
+          replyCode: defs.constants.CONNECTION_FORCED,
+          methodId: 0,
+          classId: 0,
+        }))
+        .then(wait(defs.ConnectionCloseOk))
+        .then(cb, cb);
+    }));
+
+    it('throw in close handler from client-initiated close is swallowed without handler-error listener', connectionTest((c, cb) => {
+      c.open(OPEN_OPTS, (err) => {
+        assert.ifError(err);
+        c.on('close', () => { throw new Error('user handler explodes on client close'); });
+        c.close();
+        cb();
+      });
+    }, (send, wait, cb) => {
+      handshake(send, wait)
+        .then(wait(defs.ConnectionClose))
+        .then(() => send(defs.ConnectionCloseOk, {}))
+        .then(cb, cb);
+    }));
+
+    it('throw in error handler becomes uncaught exception', connectionTest((c, cb) => {
+      const expectedErr = new Error('user error handler explodes');
+      process.once('uncaughtException', (err) => {
+        assert.strictEqual(err, expectedErr);
+        cb();
+      });
+      c.on('error', () => { throw expectedErr; });
+      c.open(OPEN_OPTS);
+    }, (send, wait, cb) => {
+      handshake(send, wait)
+        .then(() => send(defs.ConnectionClose, {
+          replyText: 'Begone',
+          replyCode: defs.constants.INTERNAL_ERROR,
+          methodId: 0,
+          classId: 0,
+        }))
+        .then(wait(defs.ConnectionCloseOk))
+        .then(cb, cb);
+    }));
+
+    it('throw in blocked handler becomes uncaught exception', connectionTest((c, cb) => {
+      const expectedErr = new Error('user blocked handler explodes');
+      process.once('uncaughtException', (err) => {
+        assert.strictEqual(err, expectedErr);
+        cb();
+      });
+      c.on('blocked', () => { throw expectedErr; });
+      c.open(OPEN_OPTS);
+    }, (send, wait, cb) => {
+      handshake(send, wait)
+        .then(() => send(defs.ConnectionBlocked, { reason: 'memory' }, 0))
+        .then(cb, cb);
+    }));
+
+    it('throw in unblocked handler becomes uncaught exception', connectionTest((c, cb) => {
+      const expectedErr = new Error('user unblocked handler explodes');
+      process.once('uncaughtException', (err) => {
+        assert.strictEqual(err, expectedErr);
+        cb();
+      });
+      c.on('unblocked', () => { throw expectedErr; });
+      c.open(OPEN_OPTS);
+    }, (send, wait, cb) => {
+      handshake(send, wait)
+        .then(() => send(defs.ConnectionUnblocked, {}, 0))
+        .then(cb, cb);
+    }));
+
+    it('throw in update-secret-ok handler becomes uncaught exception', connectionTest((c, cb) => {
+      const expectedErr = new Error('user update-secret-ok handler explodes');
+      process.once('uncaughtException', (err) => {
+        assert.strictEqual(err, expectedErr);
+        cb();
+      });
+      c.open(OPEN_OPTS, (err) => {
+        assert.ifError(err);
+        c.on('update-secret-ok', () => { throw expectedErr; });
+        c._updateSecret(Buffer.from('new secret'), 'reason', () => {});
+      });
+    }, (send, wait, cb) => {
+      handshake(send, wait)
+        .then(wait(defs.ConnectionUpdateSecret))
+        .then(() => send(defs.ConnectionUpdateSecretOk, {}, 0))
+        .then(cb, cb);
+    }));
+
+    it('throw in error handler from closeWithError becomes uncaught exception', connectionTest((c, cb) => {
+      const expectedErr = new Error('user error handler explodes on closeWithError');
+      process.once('uncaughtException', (err) => {
+        assert.strictEqual(err, expectedErr);
+        cb();
+      });
+      c.once('error', (err) => {
+        assert.match(err.message, /Unexpected frame on channel 0/);
+        throw expectedErr;
+      });
+      c.open(OPEN_OPTS);
+    }, (send, wait, cb) => {
+      handshake(send, wait)
+        .then(() => send(defs.ChannelOpenOk, { channelId: Buffer.from('') }, 0))
+        .then(cb, cb);
+    }));
+
+    it('throw in error handler from onSocketError', connectionTest((c, cb) => {
+      const expectedErr = new Error('user error handler explodes on socket error');
+      process.once('uncaughtException', (err) => {
+        assert.strictEqual(err, expectedErr);
+        cb();
+      });
+      c.once('error', (err) => {
+        assert.match(err.message, /Unexpected close/);
+        throw expectedErr;
+      });
+      c.open(OPEN_OPTS, (err) => {
+        assert.ifError(err);
+        c.sendHeartbeat();
+      });
+    }, (send, wait, cb, socket) => {
+      handshake(send, wait)
+        .then(wait())
+        .then(() => socket.end())
+        .then(cb, cb);
+    }));
+
+    it('throw in error handler from heartbeat timeout', connectionTest((c, cb) => {
+      heartbeat.UNITS_TO_MS = 20;
+      const expectedErr = new Error('user error handler explodes on heartbeat timeout');
+      const opts = Object.create(OPEN_OPTS);
+      opts.heartbeat = 1;
+      process.once('uncaughtException', (err) => {
+        assert.strictEqual(err, expectedErr);
+        c.heartbeater.clear();
+        cb();
+      });
+      c.on('error', (err) => {
+        assert.match(err.message, /Heartbeat timeout/);
+        throw expectedErr;
+      });
+      c.open(opts);
+    }, (send, wait, cb) => {
+      handshake(send, wait)
+        .then(cb, cb);
+      // conspicuously not sending anything ...
+    }));
+  });
+
+  describe('Event handler errors - with handler-error listener', () => {
+    let prevUncaughtExceptionListeners;
+
+    beforeEach(() => {
+      prevUncaughtExceptionListeners = process.rawListeners('uncaughtException').slice();
+      process.removeAllListeners('uncaughtException');
+    });
+
+    afterEach(() => {
+      prevUncaughtExceptionListeners.forEach((h) => process.on('uncaughtException', h));
+      heartbeat.UNITS_TO_MS = 1000;
+    });
+
+    it('throw in close handler is delivered via handler-error event', connectionTest((c, cb) => {
+      const expectedErr = new Error('user close handler explodes');
+      c.on('handler-error', (err, event) => {
+        assert.strictEqual(err, expectedErr);
+        assert.strictEqual(event, 'close');
+        cb();
+      });
+      c.on('close', () => { throw expectedErr; });
+      c.open(OPEN_OPTS);
+    }, (send, wait, cb) => {
+      handshake(send, wait)
+        .then(() => send(defs.ConnectionClose, {
+          replyText: 'Begone',
+          replyCode: defs.constants.CONNECTION_FORCED,
+          methodId: 0,
+          classId: 0,
+        }))
+        .then(wait(defs.ConnectionCloseOk))
+        .then(cb, cb);
+    }));
+
+    it('throw in error handler is delivered via handler-error event', connectionTest((c, cb) => {
+      const expectedErr = new Error('user error handler explodes');
+      c.on('handler-error', (err, event) => {
+        assert.strictEqual(err, expectedErr);
+        assert.strictEqual(event, 'error');
+        cb();
+      });
+      c.on('error', () => { throw expectedErr; });
+      c.open(OPEN_OPTS);
+    }, (send, wait, cb) => {
+      handshake(send, wait)
+        .then(() => send(defs.ConnectionClose, {
+          replyText: 'Begone',
+          replyCode: defs.constants.INTERNAL_ERROR,
+          methodId: 0,
+          classId: 0,
+        }))
+        .then(wait(defs.ConnectionCloseOk))
+        .then(cb, cb);
+    }));
+
+    it('throw in blocked handler is delivered via handler-error event', connectionTest((c, cb) => {
+      const expectedErr = new Error('user blocked handler explodes');
+      c.on('handler-error', (err, event) => {
+        assert.strictEqual(err, expectedErr);
+        assert.strictEqual(event, 'blocked');
+        cb();
+      });
+      c.on('blocked', () => { throw expectedErr; });
+      c.open(OPEN_OPTS);
+    }, (send, wait, cb) => {
+      handshake(send, wait)
+        .then(() => send(defs.ConnectionBlocked, { reason: 'memory' }, 0))
+        .then(cb, cb);
+    }));
+
+    it('throw in unblocked handler is delivered via handler-error event', connectionTest((c, cb) => {
+      const expectedErr = new Error('user unblocked handler explodes');
+      c.on('handler-error', (err, event) => {
+        assert.strictEqual(err, expectedErr);
+        assert.strictEqual(event, 'unblocked');
+        cb();
+      });
+      c.on('unblocked', () => { throw expectedErr; });
+      c.open(OPEN_OPTS);
+    }, (send, wait, cb) => {
+      handshake(send, wait)
+        .then(() => send(defs.ConnectionUnblocked, {}, 0))
+        .then(cb, cb);
+    }));
+
+    it('throw in update-secret-ok handler is delivered via handler-error event', connectionTest((c, cb) => {
+      const expectedErr = new Error('user update-secret-ok handler explodes');
+      c.on('handler-error', (err, event) => {
+        assert.strictEqual(err, expectedErr);
+        assert.strictEqual(event, 'update-secret-ok');
+        cb();
+      });
+      c.open(OPEN_OPTS, (err) => {
+        assert.ifError(err);
+        c.on('update-secret-ok', () => { throw expectedErr; });
+        c._updateSecret(Buffer.from('new secret'), 'reason', () => {});
+      });
+    }, (send, wait, cb) => {
+      handshake(send, wait)
+        .then(wait(defs.ConnectionUpdateSecret))
+        .then(() => send(defs.ConnectionUpdateSecretOk, {}, 0))
+        .then(cb, cb);
+    }));
+
+    it('throw in error handler from heartbeat timeout is delivered via handler-error event', connectionTest((c, cb) => {
+      heartbeat.UNITS_TO_MS = 20;
+      const expectedErr = new Error('user error handler explodes on heartbeat timeout');
+      const opts = Object.create(OPEN_OPTS);
+      opts.heartbeat = 1;
+      c.on('handler-error', (err, event) => {
+        assert.strictEqual(err, expectedErr);
+        assert.strictEqual(event, 'error');
+        c.heartbeater.clear();
+        cb();
+      });
+      c.on('error', (err) => {
+        assert.match(err.message, /Heartbeat timeout/);
+        throw expectedErr;
+      });
+      c.open(opts);
+    }, (send, wait, cb) => {
+      handshake(send, wait)
+        .then(cb, cb);
+      // conspicuously not sending anything ...
+    }));
+
+    it('throw in error handler from closeWithError is delivered via handler-error event', connectionTest((c, cb) => {
+      const expectedErr = new Error('user error handler explodes on closeWithError');
+      c.on('handler-error', (err, event) => {
+        assert.strictEqual(err, expectedErr);
+        assert.strictEqual(event, 'error');
+        cb();
+      });
+      c.once('error', (err) => {
+        assert.match(err.message, /Unexpected frame on channel 0/);
+        throw expectedErr;
+      });
+      c.open(OPEN_OPTS);
+    }, (send, wait, cb) => {
+      handshake(send, wait)
+        .then(() => send(defs.ChannelOpenOk, { channelId: Buffer.from('') }, 0))
+        .then(cb, cb);
+    }));
+
+    it('throw in error handler from onSocketError is delivered via handler-error event', connectionTest((c, cb) => {
+      const expectedErr = new Error('user error handler explodes on socket error');
+      c.on('handler-error', (err, event) => {
+        assert.strictEqual(err, expectedErr);
+        assert.strictEqual(event, 'error');
+        cb();
+      });
+      c.once('error', (err) => {
+        assert.match(err.message, /Unexpected close/);
+        throw expectedErr;
+      });
+      c.open(OPEN_OPTS, (err) => {
+        assert.ifError(err);
+        c.sendHeartbeat();
+      });
+    }, (send, wait, cb, socket) => {
+      handshake(send, wait)
+        .then(wait())
+        .then(() => socket.end())
+        .then(cb, cb);
+    }));
+
+    it('throw in handler-error handler becomes uncaught exception', connectionTest((c, cb) => {
+      const expectedErr = new Error('handler-error handler explodes');
+      process.once('uncaughtException', (err) => {
+        assert.strictEqual(err, expectedErr);
+        cb();
+      });
+      c.on('handler-error', () => { throw expectedErr; });
+      c.on('blocked', () => { throw new Error('user blocked handler explodes'); });
+      c.open(OPEN_OPTS);
+    }, (send, wait, cb) => {
+      handshake(send, wait)
+        .then(() => send(defs.ConnectionBlocked, { reason: 'memory' }, 0))
+        .then(cb, cb);
+    }));
+  });
+
   describe('heartbeats', () => {
 
     beforeEach(() => {