amqplib 2.0.1 → 2.2.0

package/.github/workflows/publish.yml

@@ -1,8 +1,25 @@
+# Runs when a GitHub release is published (draft releases do not trigger it).
+#
+# Tests the tagged commit on every supported Node.js version, then stages the
+# package on npm with `npm stage publish` using OIDC trusted publishing, so no
+# npm token is stored in this repository. Nothing goes live until a maintainer
+# reviews the staged version and approves it with 2FA:
+#
+#   npm stage list amqplib
+#   npm stage approve <stage-id>
+#
+# Prerequisites on npmjs.com: the package's trusted publisher must be set to
+# this repository and this workflow file (publish.yml), with allowed actions
+# restricted to `npm stage publish`.
+
 name: Publish
 
 on:
   release:
-    types: [created]
+    types: [published]
+
+permissions:
+  contents: read
 
 jobs:
   build:
@@ -19,17 +36,18 @@ jobs:
         # See supported Node.js release schedule at https://nodejs.org/en/about/releases/
 
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
 
       - name: Use Node.js ${{ matrix.node-version }}
-        uses: actions/setup-node@v3
+        uses: actions/setup-node@v4
         with:
           node-version: ${{ matrix.node-version }}
           cache: "npm"
 
       - run: npm ci
 
-      - run: |
+      - name: Wait for RabbitMQ
+        run: |
           n=0
           while :
           do
@@ -43,17 +61,53 @@ jobs:
 
       - run: make test
 
-  publish:
+  stage:
     needs: build
     runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write # required for OIDC trusted publishing
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
+
       - uses: actions/setup-node@v4
         with:
-          node-version: '20.x'
+          node-version: 24.x
           cache: "npm"
           registry-url: https://registry.npmjs.org/
+
+      # npm stage publish needs npm 11.15.0 or later
+      - run: npm install -g npm@^11.15.0
+
       - run: npm ci
-      - run: npm publish --dry-run
+
+      - name: Check release tag matches package.json version
+        id: version
+        env:
+          RELEASE_TAG: ${{ github.event.release.tag_name }}
+        run: |
+          version="$(node -p "require('./package.json').version")"
+          if [[ "$RELEASE_TAG" != "v${version}" ]]; then
+            echo "Release tag ${RELEASE_TAG} does not match package.json version v${version}" >&2
+            exit 1
+          fi
+          echo "version=${version}" >> "$GITHUB_OUTPUT"
+
+      # Pre-release versions (e.g. 2.2.0-rc.0) are staged under the `next`
+      # dist-tag; everything else under `latest`. The tag is fixed at staging
+      # time and cannot be changed on approval.
+      - name: Choose dist-tag
+        id: dist-tag
+        env:
+          VERSION: ${{ steps.version.outputs.version }}
+        run: |
+          if [[ "$VERSION" == *-* ]]; then
+            echo "tag=next" >> "$GITHUB_OUTPUT"
+          else
+            echo "tag=latest" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Stage publish
         env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_AUTH_TOKEN }}
+          DIST_TAG: ${{ steps.dist-tag.outputs.tag }}
+        run: npm stage publish --tag "$DIST_TAG" --provenance

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Change log for amqplib
 
+## v2.2.0
+- Add `calculateDelay` recovery option for supplying a custom reconnect delay strategy, e.g. full jitter, decorrelated jitter or a fixed schedule. When set, `maxDelay` is not applied to its return value; when it throws or returns an invalid value, recovery gives up as if `maxRetries` were exhausted (fixes #855, thanks [@GiHoon1123](https://github.com/GiHoon1123))
+- The built-in reconnect delay no longer exceeds `maxDelay`. Previously the cap was applied before jitter, so delays could overshoot it by up to the jitter fraction. The exponential base is now capped at `maxDelay / (1 + jitter)` so the full jitter range fits under the cap; with default settings the steady-state delay is now spread over 20-30s rather than 24-36s
+- Channel operations attempted after recovery has given up (`reconnect-failed`) now reject with the failure instead of waiting forever
+- Add `initialMaxRetries` recovery option to bound retries before the first successful connection separately from `maxRetries`, so startup can fail fast while steady-state recovery retries indefinitely (fixes #856)
+
+## 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,92 @@ 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.
+
+### Custom delay strategy
+
+By default, reconnect delays follow an exponential backoff with jitter,
+controlled by `initialDelay`, `maxDelay`, `factor` and `jitter`. To use a
+different strategy entirely (full jitter, decorrelated jitter, a fixed step
+schedule, etc.), provide a `calculateDelay` function instead:
+
+```javascript
+const connection = await amqplib.connect('amqp://localhost', {
+  recovery: {
+    maxRetries: Infinity,
+    // Called with the reconnect attempt number, starting at 1.
+    // Must return the delay in milliseconds.
+    calculateDelay(attempt) {
+      return Math.min(30000, 100 * 2 ** (attempt - 1));
+    },
+  },
+});
+```
+
+`maxDelay` only bounds the built-in strategy. Once you provide `calculateDelay`,
+amqplib does not cap its return value - you're responsible for enforcing your
+own maximum, as the example above does with `Math.min`.
+
+When `calculateDelay` is absent, the built-in strategy is used. If it throws,
+or returns something other than a finite, non-negative number, amqplib does
+not fall back to the built-in strategy. Instead recovery gives up as if
+`maxRetries` had been exhausted: the initial `connect` rejects (or the
+callback receives the error), pending channel operations reject, and
+`reconnect-failed` is emitted with the error. A broken `calculateDelay` is a
+bug in caller-supplied code, so it is surfaced rather than papered over.
+
+### Separate retry budget for the initial connection
+
+By default `maxRetries` bounds every phase of recovery, including the attempts
+made before the first connection succeeds. To give the very first connection
+its own budget, set `initialMaxRetries`; once connected, `maxRetries` applies.
+A common production posture is to fail fast at startup, so a misconfigured or
+unreachable broker fails the deployment, while never giving up on a service
+that has already connected:
+
+```javascript
+const connection = await amqplib.connect('amqp://localhost', {
+  recovery: {
+    initialMaxRetries: 5, // give up (and reject connect) after 5 failed retries at startup
+    maxRetries: Infinity, // but keep reconnecting forever once connected
+  },
+});
+```
+
+When the initial budget is exhausted `connect` rejects (or the callback receives
+the error) and `reconnect-failed` is emitted. `initialMaxRetries` defaults to
+`maxRetries`, so behaviour is unchanged unless it is set.
+
 ## Error handling in event handlers
 
 If a user-supplied event handler throws a synchronous error, the throw will

package/callback_api.d.ts

@@ -169,13 +169,37 @@ export interface RecoveryOptions {
   factor?: number;
   /** Jitter factor (0–1) applied to delay to avoid thundering herd. Default: 0.2 */
   jitter?: number;
-  /** Maximum number of reconnect attempts. Default: Infinity */
+  /** Maximum number of reconnect attempts. Also bounds the initial connection unless `initialMaxRetries` is set. Default: Infinity */
   maxRetries?: number;
+  /**
+   * Maximum number of retries before the first successful connection. Once
+   * connected, `maxRetries` applies instead. Lets startup fail fast against an
+   * unreachable broker while steady-state recovery keeps retrying.
+   * Default: the value of `maxRetries`
+   */
+  initialMaxRetries?: 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;
+  /**
+   * Optional custom delay strategy. Called with the reconnect attempt number
+   * (starting at 1) and must return the delay in milliseconds. Falls back to
+   * the built-in exponential-backoff-with-jitter strategy when absent. If it
+   * throws, or returns something other than a finite, non-negative number,
+   * recovery gives up as if `maxRetries` were exhausted: the initial connection
+   * fails with the error and `reconnect-failed` is emitted.
+   */
+  calculateDelay?: (attempt: number) => number;
 }
 
 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 +229,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

@@ -143,13 +143,38 @@ export interface RecoveryOptions {
   factor?: number;
   /** Jitter factor (0–1) applied to delay to avoid thundering herd. Default: 0.2 */
   jitter?: number;
-  /** Maximum number of reconnect attempts. Default: Infinity */
+  /** Maximum number of reconnect attempts. Also bounds the initial connection unless `initialMaxRetries` is set. Default: Infinity */
   maxRetries?: number;
+  /**
+   * Maximum number of retries before the first successful connection. Once
+   * connected, `maxRetries` applies instead. Lets startup fail fast against an
+   * unreachable broker while steady-state recovery keeps retrying.
+   * Default: the value of `maxRetries`
+   */
+  initialMaxRetries?: 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;
+  /**
+   * Optional custom delay strategy. Called with the reconnect attempt number
+   * (starting at 1) and must return the delay in milliseconds. Falls back to
+   * the built-in exponential-backoff-with-jitter strategy when absent. If it
+   * throws, or returns something other than a finite, non-negative number,
+   * recovery gives up as if `maxRetries` were exhausted: the initial connection
+   * fails with the error and `reconnect-failed` is emitted.
+   */
+  calculateDelay?: (attempt: number) => number;
 }
 
 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,8 @@ const DEFAULT_RECOVERY = {
   jitter: 0.2,
   maxRetries: Infinity,
   setup: null,
+  waitForConnect: true,
+  calculateDelay: null,
 };
 
 function splitConnectionOptions(connOptions) {
@@ -42,21 +44,32 @@ function toFiniteNumber(value, fallback) {
   return Number.isFinite(n) ? n : fallback;
 }
 
+function toRetryCount(value, fallback) {
+  if (value == null) return fallback;
+  if (value === Infinity) return Infinity;
+  const n = toFiniteNumber(value, fallback);
+  return n < 0 ? 0 : n;
+}
+
 function normaliseRecoveryOptions(recovery) {
   const source = recovery === true ? {} : recovery || {};
   const initialDelay = Math.max(0, toFiniteNumber(source.initialDelay, DEFAULT_RECOVERY.initialDelay));
   const maxDelay = Math.max(initialDelay, toFiniteNumber(source.maxDelay, DEFAULT_RECOVERY.maxDelay));
   const factor = Math.max(1, toFiniteNumber(source.factor, DEFAULT_RECOVERY.factor));
   const jitter = Math.min(1, Math.max(0, toFiniteNumber(source.jitter, DEFAULT_RECOVERY.jitter)));
-  const parsedMaxRetries = source.maxRetries == null ? Infinity : toFiniteNumber(source.maxRetries, Infinity);
+  const maxRetries = toRetryCount(source.maxRetries, Infinity);
+  const initialMaxRetries = toRetryCount(source.initialMaxRetries, maxRetries);
 
   return {
     initialDelay,
     maxDelay,
     factor,
     jitter,
-    maxRetries: parsedMaxRetries < 0 ? 0 : parsedMaxRetries,
+    maxRetries,
+    initialMaxRetries,
     setup: typeof source.setup === 'function' ? source.setup : null,
+    waitForConnect: source.waitForConnect !== false,
+    calculateDelay: typeof source.calculateDelay === 'function' ? source.calculateDelay : null,
   };
 }
 
@@ -65,13 +78,39 @@ function toError(err, fallbackMessage) {
   return new Error(err ? String(err) : fallbackMessage);
 }
 
-function calculateDelay(recovery, attempt) {
-  const base = Math.min(recovery.maxDelay, recovery.initialDelay * recovery.factor ** (attempt - 1));
+function calculateBuiltinDelay(recovery, attempt) {
+  // Capping the base at maxDelay and then clamping base+offset to maxDelay
+  // would put a point mass on maxDelay itself: once base saturates, every
+  // positive jitter draw (half of them) collapses onto the same value,
+  // defeating the point of jitter. Capping the base at
+  // maxDelay / (1 + jitter) instead means the maximum possible offset
+  // lands exactly on maxDelay, so the result never exceeds it without
+  // needing a final clamp - the distribution stays smooth right up to the cap.
+  const cappedBase = recovery.maxDelay / (1 + recovery.jitter);
+  const base = Math.min(cappedBase, recovery.initialDelay * recovery.factor ** (attempt - 1));
   const jitterPart = base * recovery.jitter;
   const offset = jitterPart > 0 ? Math.random() * jitterPart * 2 - jitterPart : 0;
   return Math.max(0, Math.round(base + offset));
 }
 
+// A custom `calculateDelay` that throws, or returns something other than a
+// finite, non-negative number, is a bug in caller-supplied code. Rather than
+// silently falling back to the built-in strategy, the error is treated as a
+// terminal recovery failure by the caller (see _scheduleReconnect), so it
+// surfaces immediately instead of manifesting as unexplained delay behavior.
+function calculateDelay(recovery, attempt) {
+  if (!recovery.calculateDelay) {
+    return calculateBuiltinDelay(recovery, attempt);
+  }
+
+  const custom = recovery.calculateDelay(attempt);
+  if (typeof custom === 'number' && Number.isFinite(custom) && custom >= 0) {
+    return Math.round(custom);
+  }
+
+  throw new Error(`calculateDelay must return a finite, non-negative number of milliseconds (got ${String(custom)})`);
+}
+
 function runSetup(setup, model) {
   if (!setup) return Promise.resolve();
 
@@ -116,6 +155,8 @@ class RecoveringCore extends EventEmitter {
     this._waiters = [];
     this._connecting = false;
     this._stopped = false;
+    this._failure = null;
+    this._connectedOnce = false;
     this._timer = null;
     this._attempt = 0;
 
@@ -124,8 +165,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() {
@@ -196,7 +244,7 @@ class RecoveringCore extends EventEmitter {
 
   _waitForConnection() {
     if (this._model) return Promise.resolve(this._model);
-    if (this._stopped) return Promise.reject(new Error('Connection closed'));
+    if (this._stopped) return Promise.reject(this._failure || new Error('Connection closed'));
 
     return new Promise((resolve, reject) => {
       this._waiters.push({ resolve, reject });
@@ -260,7 +308,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;
@@ -268,6 +316,7 @@ class RecoveringCore extends EventEmitter {
 
       this._model = model;
       this._attempt = 0;
+      this._connectedOnce = true;
       this._bindModel(model);
       this._resolveInitialConnection();
       this._resolvePendingWaiters(model);
@@ -287,15 +336,24 @@ class RecoveringCore extends EventEmitter {
 
     if (this._timer) return;
 
-    if (this._attempt >= this._recovery.maxRetries) {
-      this._rejectInitialConnection(err);
-      this._rejectPendingWaiters(err);
-      this.emit('reconnect-failed', err);
+    const maxRetries = this._connectedOnce ? this._recovery.maxRetries : this._recovery.initialMaxRetries;
+    if (this._attempt >= maxRetries) {
+      this._abandonRecovery(err);
       return;
     }
 
     const attempt = this._attempt + 1;
-    const delay = calculateDelay(this._recovery, attempt);
+    let delay;
+    try {
+      delay = calculateDelay(this._recovery, attempt);
+    } catch (delayErr) {
+      // Both callers of _scheduleReconnect run from timers or socket events
+      // where a throw would either be an unhandled rejection or an uncaught
+      // exception. Give up recovery cleanly instead so the failure reaches the
+      // initial connect promise, pending channel waiters and 'reconnect-failed'.
+      this._abandonRecovery(toError(delayErr, 'calculateDelay failed'));
+      return;
+    }
     this._attempt = attempt;
 
     this.emit('reconnect-scheduled', { attempt, delay, error: err });
@@ -305,6 +363,18 @@ class RecoveringCore extends EventEmitter {
     }, delay);
   }
 
+  _abandonRecovery(err) {
+    // Recovery is over and cannot be restarted, so treat the connection as
+    // stopped. Remember why, so channel operations attempted afterwards
+    // reject with the underlying failure instead of waiting forever for a
+    // connection that will never arrive.
+    this._stopped = true;
+    this._failure = err;
+    this._rejectInitialConnection(err);
+    this._rejectPendingWaiters(err);
+    this.emit('reconnect-failed', err);
+  }
+
   _closeModelNoThrow(model) {
     return this._adapters.closeModel(model).catch(() => {});
   }
@@ -452,12 +522,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.2.0",
   "types": "./index.d.ts",
   "exports": {
     ".": {

package/test/recovery.test.js

@@ -1,5 +1,3 @@
-
-
 const { describe, it } = require('node:test');
 const assert = require('node:assert');
 const EventEmitter = require('node:events');
@@ -16,11 +14,11 @@ class FakePromiseModel extends EventEmitter {
   }
 
   createChannel(options) {
-    return Promise.resolve({kind: 'channel', id: this.id, options});
+    return Promise.resolve({ kind: 'channel', id: this.id, options });
   }
 
   createConfirmChannel(options) {
-    return Promise.resolve({kind: 'confirm', id: this.id, options});
+    return Promise.resolve({ kind: 'confirm', id: this.id, options });
   }
 
   updateSecret(_newSecret, _reason) {
@@ -43,7 +41,7 @@ class FakeCallbackModel extends EventEmitter {
       cb = options;
       options = undefined;
     }
-    cb && cb(null, {kind: 'channel', id: this.id, options});
+    cb && cb(null, { kind: 'channel', id: this.id, options });
   }
 
   createConfirmChannel(options, cb) {
@@ -51,7 +49,7 @@ class FakeCallbackModel extends EventEmitter {
       cb = options;
       options = undefined;
     }
-    cb && cb(null, {kind: 'confirm', id: this.id, options});
+    cb && cb(null, { kind: 'confirm', id: this.id, options });
   }
 
   updateSecret(_newSecret, _reason, cb) {
@@ -199,6 +197,303 @@ describe('recovery', () => {
     await client.close();
   });
 
+  it('built-in delay never exceeds maxDelay even at full jitter', async () => {
+    const models = [];
+    let opened = 0;
+
+    function openModel() {
+      const model = new FakePromiseModel(++opened);
+      models.push(model);
+      return Promise.resolve(model);
+    }
+
+    const client = await recovery.connectWithRecoveryPromise(openModel, {
+      initialDelay: 5,
+      maxDelay: 5,
+      factor: 1,
+      jitter: 1,
+      maxRetries: Infinity,
+    });
+
+    const originalRandom = Math.random;
+    let delay;
+
+    try {
+      // Force the maximum positive jitter. The base is capped at
+      // maxDelay / (1 + jitter) = 2.5, so base + offset tops out at
+      // exactly maxDelay (5) instead of overshooting it.
+      Math.random = () => 1;
+
+      delay = await new Promise((resolve) => {
+        client.once('reconnect-scheduled', (info) => resolve(info.delay));
+        models[models.length - 1].emit('close', new Error('socket closed'));
+      });
+    } finally {
+      Math.random = originalRandom;
+      await client.close();
+    }
+
+    assert.equal(delay, 5);
+  });
+
+  it('does not collapse onto maxDelay for every positive jitter draw once the base saturates', async () => {
+    const models = [];
+    let opened = 0;
+
+    function openModel() {
+      const model = new FakePromiseModel(++opened);
+      models.push(model);
+      return Promise.resolve(model);
+    }
+
+    const client = await recovery.connectWithRecoveryPromise(openModel, {
+      initialDelay: 100,
+      maxDelay: 100,
+      factor: 1,
+      jitter: 0.2,
+      maxRetries: Infinity,
+    });
+
+    const originalRandom = Math.random;
+    let delay;
+
+    try {
+      // Math.random() just above the midpoint gives a small positive
+      // offset. Capping base+offset at maxDelay (the old behavior) would
+      // collapse this to exactly 100 instead of the slightly lower value
+      // this offset actually produces.
+      Math.random = () => 0.6;
+
+      delay = await new Promise((resolve) => {
+        client.once('reconnect-scheduled', (info) => resolve(info.delay));
+        models[models.length - 1].emit('close', new Error('socket closed'));
+      });
+    } finally {
+      Math.random = originalRandom;
+      await client.close();
+    }
+
+    // base = 100 / 1.2 = 83.33, jitterPart = 16.67,
+    // offset = 0.6 * 16.67 * 2 - 16.67 = 3.33, result = round(83.33 + 3.33) = 87
+    assert.equal(delay, 87);
+    assert.notEqual(delay, 100);
+  });
+
+  it('uses a custom calculateDelay strategy when provided', async () => {
+    const models = [];
+    let opened = 0;
+    const attemptsSeen = [];
+
+    function openModel() {
+      const model = new FakePromiseModel(++opened);
+      models.push(model);
+      return Promise.resolve(model);
+    }
+
+    const client = await recovery.connectWithRecoveryPromise(openModel, {
+      initialDelay: 1,
+      maxDelay: 1,
+      jitter: 0,
+      maxRetries: 3,
+      calculateDelay(attempt) {
+        attemptsSeen.push(attempt);
+        return attempt * 1000;
+      },
+    });
+
+    await new Promise((resolve) => {
+      client.once('reconnect-scheduled', ({ attempt, delay }) => {
+        assert.equal(1, attempt);
+        assert.equal(1000, delay);
+        resolve();
+      });
+
+      models[0].emit('close', new Error('socket closed'));
+    });
+
+    assert.deepEqual([1], attemptsSeen);
+
+    await client.close();
+  });
+
+  it('gives up recovery with reconnect-failed when calculateDelay throws', async () => {
+    const models = [];
+    let opened = 0;
+
+    function openModel() {
+      const model = new FakePromiseModel(++opened);
+      models.push(model);
+      return Promise.resolve(model);
+    }
+
+    const client = await recovery.connectWithRecoveryPromise(openModel, {
+      initialDelay: 5,
+      maxDelay: 5,
+      jitter: 0,
+      maxRetries: 3,
+      calculateDelay() {
+        throw new Error('calculateDelay is broken');
+      },
+    });
+
+    const err = await new Promise((resolve) => {
+      client.once('reconnect-failed', resolve);
+      models[0].emit('close', new Error('socket closed'));
+    });
+    assert.match(err.message, /calculateDelay is broken/);
+    await assert.rejects(client.createChannel(), /calculateDelay is broken/);
+
+    await client.close();
+  });
+
+  it('reports a validation error instead of a JSON error for a circular-reference return value', async () => {
+    const models = [];
+    let opened = 0;
+
+    function openModel() {
+      const model = new FakePromiseModel(++opened);
+      models.push(model);
+      return Promise.resolve(model);
+    }
+
+    const client = await recovery.connectWithRecoveryPromise(openModel, {
+      initialDelay: 5,
+      maxDelay: 5,
+      jitter: 0,
+      maxRetries: 3,
+      calculateDelay() {
+        const circular = {};
+        circular.self = circular;
+        return circular;
+      },
+    });
+
+    // Must be our own validation error, not a JSON.stringify TypeError from
+    // trying to serialize the circular value into the message.
+    const err = await new Promise((resolve) => {
+      client.once('reconnect-failed', resolve);
+      models[0].emit('close', new Error('socket closed'));
+    });
+    assert.match(err.message, /calculateDelay must return a finite, non-negative number/);
+
+    await client.close();
+  });
+
+  it('gives up recovery when calculateDelay returns an invalid value', async () => {
+    const models = [];
+    let opened = 0;
+
+    function openModel() {
+      const model = new FakePromiseModel(++opened);
+      models.push(model);
+      return Promise.resolve(model);
+    }
+
+    const client = await recovery.connectWithRecoveryPromise(openModel, {
+      initialDelay: 5,
+      maxDelay: 5,
+      jitter: 0,
+      maxRetries: 3,
+      calculateDelay() {
+        return -1;
+      },
+    });
+
+    const err = await new Promise((resolve) => {
+      client.once('reconnect-failed', resolve);
+      models[0].emit('close', new Error('socket closed'));
+    });
+    assert.match(err.message, /calculateDelay must return a finite, non-negative number/);
+
+    await client.close();
+  });
+
+  it('does not coerce non-number calculateDelay return values', async () => {
+    const models = [];
+    let opened = 0;
+
+    function openModel() {
+      const model = new FakePromiseModel(++opened);
+      models.push(model);
+      return Promise.resolve(model);
+    }
+
+    const client = await recovery.connectWithRecoveryPromise(openModel, {
+      initialDelay: 5,
+      maxDelay: 5,
+      jitter: 0,
+      maxRetries: 3,
+      calculateDelay() {
+        return '1000'; // a string, not a number - must not be accepted as-is
+      },
+    });
+
+    const err = await new Promise((resolve) => {
+      client.once('reconnect-failed', resolve);
+      models[0].emit('close', new Error('socket closed'));
+    });
+    assert.match(err.message, /calculateDelay must return a finite, non-negative number/);
+
+    await client.close();
+  });
+
+  it('rejects the initial connection when calculateDelay throws after a failed connect', async (t) => {
+    const rejections = [];
+    const onRejection = (err) => rejections.push(err);
+    process.on('unhandledRejection', onRejection);
+    t.after(() => process.removeListener('unhandledRejection', onRejection));
+
+    let attempts = 0;
+
+    function openModel() {
+      attempts++;
+      return Promise.reject(new Error('connect failed'));
+    }
+
+    await assert.rejects(
+      recovery.connectWithRecoveryPromise(openModel, {
+        maxRetries: Infinity,
+        calculateDelay() {
+          throw new Error('calculateDelay is broken');
+        },
+      }),
+      /calculateDelay is broken/,
+    );
+
+    await new Promise((resolve) => setImmediate(resolve));
+    assert.equal(1, attempts);
+    assert.deepEqual([], rejections);
+  });
+
+  it('channel operations reject with the failure once recovery has given up', async () => {
+    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.createChannel(), { message: 'connect failed' });
+    await assert.rejects(client.createConfirmChannel(), { message: 'connect failed' });
+    await assert.rejects(client.updateSecret(Buffer.from('x'), 'rotate'), { message: 'connect failed' });
+
+    // Nothing further is attempted and close() is a no-op.
+    await client.close();
+    assert.equal(2, attempts);
+  });
+
   it('promise recovery fails after max retries', async () => {
     let attempts = 0;
 
@@ -223,4 +518,282 @@ describe('recovery', () => {
     assert(failed);
     assert.equal(2, attempts);
   });
+
+  describe('initialMaxRetries', () => {
+    it('bounds the initial connection separately from maxRetries', async () => {
+      let attempts = 0;
+
+      function openModel() {
+        attempts++;
+        return Promise.reject(new Error('connect failed'));
+      }
+
+      await assert.rejects(
+        recovery.connectWithRecoveryPromise(openModel, {
+          initialDelay: 1,
+          maxDelay: 1,
+          jitter: 0,
+          initialMaxRetries: 2,
+          maxRetries: Infinity,
+        }),
+        { message: 'connect failed' },
+      );
+
+      assert.equal(3, attempts);
+    });
+
+    it('stops applying once a connection has been established', async () => {
+      const models = [];
+      let attempts = 0;
+
+      function openModel() {
+        attempts++;
+        // Succeed at first, fail twice after the disconnect, then succeed again.
+        if (attempts === 2 || attempts === 3) return Promise.reject(new Error('connect failed'));
+        const model = new FakePromiseModel(attempts);
+        models.push(model);
+        return Promise.resolve(model);
+      }
+
+      const client = await recovery.connectWithRecoveryPromise(openModel, {
+        initialDelay: 1,
+        maxDelay: 1,
+        jitter: 0,
+        initialMaxRetries: 0,
+        maxRetries: 3,
+      });
+
+      const failures = [];
+      client.on('reconnect-failed', (err) => failures.push(err));
+
+      const reconnected = new Promise((resolve) => client.once('connect', resolve));
+      models[0].emit('close', new Error('socket closed'));
+      await reconnected;
+
+      assert.equal(4, attempts);
+      assert.deepEqual([], failures);
+
+      await client.close();
+    });
+
+    it('accepts Infinity explicitly even when maxRetries is finite', async () => {
+      let attempts = 0;
+
+      function openModel() {
+        attempts++;
+        if (attempts < 4) return Promise.reject(new Error('connect failed'));
+        return Promise.resolve(new FakePromiseModel(attempts));
+      }
+
+      const client = await recovery.connectWithRecoveryPromise(openModel, {
+        initialDelay: 1,
+        maxDelay: 1,
+        jitter: 0,
+        initialMaxRetries: Infinity,
+        maxRetries: 1,
+      });
+
+      assert.equal(4, attempts);
+      await client.close();
+    });
+
+    it('rejects the callback connect once the initial budget is exhausted', (_t, done) => {
+      let attempts = 0;
+
+      function openModel() {
+        attempts++;
+        return Promise.reject(new Error('connect failed'));
+      }
+
+      recovery.connectWithRecoveryCallback(
+        openModel,
+        { initialDelay: 1, maxDelay: 1, jitter: 0, initialMaxRetries: 1, maxRetries: Infinity },
+        (err) => {
+          try {
+            assert.equal('connect failed', err.message);
+            assert.equal(2, attempts);
+            done();
+          } catch (e) {
+            done(e);
+          }
+        },
+      );
+    });
+  });
+
+  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);
+    });
+  });
 });