amqplib 2.0.1 → 2.1.0

package/.claude/settings.local.json

@@ -0,0 +1,7 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(gh pr *)"
+    ]
+  }
+}

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Change log for amqplib
 
+## v2.1.0
+- Add `waitForConnect` recovery option. When `false`, `connect` returns the recovering connection immediately instead of waiting for the first successful connection, so listeners for `connect`, `connect-failed` and `reconnect-scheduled` can be attached before the initial attempt, and `close()` can cancel it. Expose `waitForConnect()` on recovering connections to await the first connection (fixes #858)
+- Fix `setup` being run when `close()` is called while the initial connection attempt is in flight
+
 ## v2.0.1
 - Remove `buffer-more-ints` dependency; use Node.js built-in BigInt Buffer methods (`readBigInt64BE`, `readBigUInt64BE`, `writeBigInt64BE`, `writeBigUInt64BE`) which have been available since Node.js v10.4
 

package/README.md

@@ -5,7 +5,7 @@
 [![Node.js CI](https://github.com/amqp-node/amqplib/workflows/Node.js%20CI/badge.svg)](https://github.com/amqp-node/amqplib/actions?query=workflow%3A%22Node.js+CI%22)
 [![amqplib](https://snyk.io/advisor/npm-package/amqplib/badge.svg)](https://snyk.io/advisor/npm-package/amqplib)
 
-A library for making AMQP 0-9-1 clients for Node.JS, and an AMQP 0-9-1 client for Node.JS v10+. This library does not implement [AMQP1.0](https://github.com/amqp-node/amqplib/issues/63) or [AMQP0-10](https://github.com/amqp-node/amqplib/issues/94).
+A library for making AMQP 0-9-1 clients for Node.JS, and an AMQP 0-9-1 client for Node.JS v18+. This library does not implement [AMQP1.0](https://github.com/amqp-node/amqplib/issues/63) or [AMQP0-10](https://github.com/amqp-node/amqplib/issues/94).
 
     npm install amqplib
 
@@ -178,6 +178,38 @@ amqplib.connect(
 
 Without `recovery` options, behavior is unchanged.
 
+### Attaching listeners before the first connection
+
+By default `connect` waits for the first successful connection before
+resolving (or invoking the callback), so events emitted during the initial
+attempt such as `connect-failed` and `reconnect-scheduled` cannot be observed.
+Set `waitForConnect: false` to get the connection handle immediately. You can
+then attach listeners, call `waitForConnect()` to await the first connection,
+or call `close()` to cancel the initial attempt. Channel operations wait for a
+connection internally, so `createChannel()` can be called straight away.
+
+```javascript
+const connection = await amqplib.connect('amqp://localhost', {
+  recovery: { waitForConnect: false },
+});
+
+connection.on('connect-failed', (err) => {
+  console.warn('connection attempt failed', err.message);
+});
+
+connection.on('reconnect-scheduled', ({ attempt, delay }) => {
+  console.log(`retrying (attempt ${attempt}) in ${delay}ms`);
+});
+
+await connection.waitForConnect();
+```
+
+The callback API returns the connection handle synchronously, so listeners can
+always be attached before the first attempt. With `waitForConnect: false` the
+callback is invoked immediately with the handle instead of after the first
+connection, and `waitForConnect(callback)` can be used to be notified once
+connected.
+
 ## Error handling in event handlers
 
 If a user-supplied event handler throws a synchronous error, the throw will

package/callback_api.d.ts

@@ -173,9 +173,17 @@ export interface RecoveryOptions {
   maxRetries?: number;
   /** Optional setup function called after each successful connection */
   setup?: ((model: Connection) => Promise<void>) | ((model: Connection, done: (err?: Error) => void) => void);
+  /**
+   * When false, the `connect()` callback is invoked immediately with the
+   * recovering connection without waiting for the first successful connection.
+   * Use `waitForConnect()` to be notified of the first connection. Default: true
+   */
+  waitForConnect?: boolean;
 }
 
 export interface RecoveringConnection extends events.EventEmitter {
+  /** Invokes the callback once the first connection has been established */
+  waitForConnect(callback: (err: Error, connection: RecoveringConnection) => void): void;
   close(callback?: (err: Error) => void): void;
   createChannel(callback: (err: Error, channel: Channel) => void): Channel;
   createChannel(options: ChannelOptions, callback: (err: Error, channel: Channel) => void): Channel;
@@ -205,5 +213,5 @@ export declare function connect(
 export declare function connect(
   url: string | Options.Connect,
   socketOptions: SocketOptions & { recovery: RecoveryOptions | true },
-  callback: (err: Error, connection: RecoveringConnection) => void,
+  callback?: (err: Error, connection: RecoveringConnection) => void,
 ): RecoveringConnection;

package/index.d.ts

@@ -147,9 +147,18 @@ export interface RecoveryOptions {
   maxRetries?: number;
   /** Optional setup function called after each successful connection */
   setup?: ((model: ChannelModel) => Promise<void>) | ((model: ChannelModel, done: (err?: Error) => void) => void);
+  /**
+   * When false, `connect()` resolves immediately with the recovering connection
+   * without waiting for the first successful connection, so listeners can be
+   * attached before the initial attempt. Use `waitForConnect()` to await the
+   * first connection. Default: true
+   */
+  waitForConnect?: boolean;
 }
 
 export interface RecoveringChannelModel extends events.EventEmitter {
+  /** Resolves once the first connection has been established */
+  waitForConnect(): Promise<this>;
   close(): Promise<void>;
   createChannel(options?: ChannelOptions): Promise<Channel>;
   createConfirmChannel(options?: ChannelOptions): Promise<ConfirmChannel>;

package/lib/recovery.js

@@ -7,6 +7,7 @@ const DEFAULT_RECOVERY = {
   jitter: 0.2,
   maxRetries: Infinity,
   setup: null,
+  waitForConnect: true,
 };
 
 function splitConnectionOptions(connOptions) {
@@ -57,6 +58,7 @@ function normaliseRecoveryOptions(recovery) {
     jitter,
     maxRetries: parsedMaxRetries < 0 ? 0 : parsedMaxRetries,
     setup: typeof source.setup === 'function' ? source.setup : null,
+    waitForConnect: source.waitForConnect !== false,
   };
 }
 
@@ -124,8 +126,15 @@ class RecoveringCore extends EventEmitter {
       this._resolveInitial = resolve;
       this._rejectInitial = reject;
     });
-
-    this._connect();
+    // The initial connection promise is only consumed if the caller opts to
+    // wait for it, so swallow rejections here to avoid unhandled rejections
+    // when close() is called or retries are exhausted before anyone awaits it.
+    this._initialWait.catch(() => {});
+
+    // Defer the first attempt so callers that receive the model before the
+    // initial connection have a chance to attach listeners before any
+    // 'connect', 'connect-failed' or 'reconnect-scheduled' events are emitted.
+    setImmediate(() => this._connect());
   }
 
   waitForConnect() {
@@ -260,7 +269,7 @@ class RecoveringCore extends EventEmitter {
     let model;
     try {
       model = await this._openModel();
-      await runSetup(this._recovery.setup, model);
+      if (!this._stopped) await runSetup(this._recovery.setup, model);
       if (this._stopped) {
         await this._closeModelNoThrow(model);
         return;
@@ -452,12 +461,17 @@ class RecoveringCallbackModel extends EventEmitter {
 
 function connectWithRecoveryPromise(openModel, recovery) {
   const recovering = new RecoveringPromiseModel(openModel, recovery);
+  if (!recovering._core._recovery.waitForConnect) return Promise.resolve(recovering);
   return recovering.waitForConnect();
 }
 
 function connectWithRecoveryCallback(openModel, recovery, cb) {
   const recovering = new RecoveringCallbackModel(openModel, recovery);
-  recovering.waitForConnect(cb);
+  if (recovering._core._recovery.waitForConnect) {
+    recovering.waitForConnect(cb);
+  } else if (typeof cb === 'function') {
+    process.nextTick(cb, null, recovering);
+  }
   return recovering;
 }
 

package/package.json

@@ -2,7 +2,7 @@
   "name": "amqplib",
   "homepage": "http://amqp-node.github.io/amqplib/",
   "main": "./channel_api.js",
-  "version": "2.0.1",
+  "version": "2.1.0",
   "types": "./index.d.ts",
   "exports": {
     ".": {

package/test/recovery.test.js

@@ -223,4 +223,180 @@ describe('recovery', () => {
     assert(failed);
     assert.equal(2, attempts);
   });
+
+  describe('waitForConnect: false', () => {
+    function watchUnhandledRejections(t) {
+      const rejections = [];
+      const onRejection = (err) => rejections.push(err);
+      process.on('unhandledRejection', onRejection);
+      t.after(() => process.removeListener('unhandledRejection', onRejection));
+      return rejections;
+    }
+
+    it('promise connect resolves before the first connection and later emits connect', async () => {
+      let opened = 0;
+
+      function openModel() {
+        return Promise.resolve(new FakePromiseModel(++opened));
+      }
+
+      const client = await recovery.connectWithRecoveryPromise(openModel, {waitForConnect: false});
+
+      assert.equal(0, opened);
+
+      const model = await new Promise((resolve) => client.once('connect', resolve));
+      assert.equal(1, model.id);
+      assert.equal(1, opened);
+
+      await client.close();
+    });
+
+    it('listeners attached after connect observe a failed first attempt', async () => {
+      let attempts = 0;
+
+      function openModel() {
+        attempts++;
+        return attempts === 1 ? Promise.reject(new Error('broker unavailable')) : Promise.resolve(new FakePromiseModel(attempts));
+      }
+
+      const client = await recovery.connectWithRecoveryPromise(openModel, {
+        initialDelay: 1,
+        maxDelay: 1,
+        jitter: 0,
+        waitForConnect: false,
+      });
+
+      const failures = [];
+      const scheduled = [];
+      client.on('connect-failed', (err) => failures.push(err));
+      client.on('reconnect-scheduled', (info) => scheduled.push(info));
+
+      await client.waitForConnect();
+
+      assert.equal(1, failures.length);
+      assert.equal('broker unavailable', failures[0].message);
+      assert.equal(1, scheduled.length);
+      assert.equal(1, scheduled[0].attempt);
+      assert.strictEqual(failures[0], scheduled[0].error);
+      assert.equal(2, attempts);
+
+      await client.close();
+    });
+
+    it('waitForConnect resolves with the recovering model once connected', async () => {
+      function openModel() {
+        return Promise.resolve(new FakePromiseModel(1));
+      }
+
+      const client = await recovery.connectWithRecoveryPromise(openModel, {waitForConnect: false});
+      const connected = await client.waitForConnect();
+
+      assert.strictEqual(client, connected);
+      const ch = await client.createChannel();
+      assert.equal(1, ch.id);
+
+      await client.close();
+    });
+
+    it('close before the first connection cancels it without an unhandled rejection', async (t) => {
+      const rejections = watchUnhandledRejections(t);
+      let setupCalls = 0;
+      let closeCalls = 0;
+      let releaseOpen;
+
+      function openModel() {
+        return new Promise((resolve) => {
+          const model = new FakePromiseModel(1);
+          model.close = () => {
+            closeCalls++;
+            return Promise.resolve();
+          };
+          releaseOpen = () => resolve(model);
+        });
+      }
+
+      const client = await recovery.connectWithRecoveryPromise(openModel, {
+        waitForConnect: false,
+        setup() {
+          setupCalls++;
+        },
+      });
+
+      let connected = false;
+      client.on('connect', () => {
+        connected = true;
+      });
+
+      const pendingChannel = client.createChannel();
+      await new Promise((resolve) => setImmediate(resolve));
+      assert(releaseOpen, 'open should be in flight');
+
+      await client.close();
+
+      await assert.rejects(pendingChannel, {message: 'Connection closed'});
+      await assert.rejects(client.waitForConnect(), {message: 'Connection closed'});
+
+      releaseOpen();
+      await new Promise((resolve) => setImmediate(resolve));
+
+      assert.equal(0, setupCalls);
+      assert.equal(1, closeCalls);
+      assert.equal(false, connected);
+      assert.deepEqual([], rejections);
+    });
+
+    it('exhausting retries emits reconnect-failed without an unhandled rejection', async (t) => {
+      const rejections = watchUnhandledRejections(t);
+      let attempts = 0;
+
+      function openModel() {
+        attempts++;
+        return Promise.reject(new Error('connect failed'));
+      }
+
+      const client = await recovery.connectWithRecoveryPromise(openModel, {
+        initialDelay: 1,
+        maxDelay: 1,
+        jitter: 0,
+        maxRetries: 1,
+        waitForConnect: false,
+      });
+
+      const err = await new Promise((resolve) => client.once('reconnect-failed', resolve));
+      assert.equal('connect failed', err.message);
+      assert.equal(2, attempts);
+
+      await assert.rejects(client.waitForConnect(), {message: 'connect failed'});
+      await new Promise((resolve) => setImmediate(resolve));
+      assert.deepEqual([], rejections);
+
+      await client.close();
+    });
+
+    it('callback connect invokes the callback before the first connection', (_t, done) => {
+      let opened = 0;
+
+      function openModel() {
+        return Promise.resolve(new FakeCallbackModel(++opened));
+      }
+
+      const failures = [];
+      const client = recovery.connectWithRecoveryCallback(openModel, {waitForConnect: false}, (err, c) => {
+        if (err) return done(err);
+        assert.strictEqual(client, c);
+        assert.equal(0, opened);
+
+        c.on('connect-failed', (failure) => failures.push(failure));
+        c.waitForConnect((waitErr, connected) => {
+          if (waitErr) return done(waitErr);
+          assert.strictEqual(client, connected);
+          assert.equal(1, opened);
+          assert.deepEqual([], failures);
+          c.close(done);
+        });
+      });
+
+      assert(client);
+    });
+  });
 });