amqplib 2.1.0 → 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,11 @@
 # 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

package/README.md

@@ -210,6 +210,60 @@ 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,8 +169,15 @@ 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);
   /**
@@ -179,6 +186,15 @@ export interface RecoveryOptions {
    * 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 {

package/index.d.ts

@@ -143,8 +143,15 @@ 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);
   /**
@@ -154,6 +161,15 @@ export interface RecoveryOptions {
    * 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 {

package/lib/recovery.js

@@ -8,6 +8,7 @@ const DEFAULT_RECOVERY = {
   maxRetries: Infinity,
   setup: null,
   waitForConnect: true,
+  calculateDelay: null,
 };
 
 function splitConnectionOptions(connOptions) {
@@ -43,22 +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,
   };
 }
 
@@ -67,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();
 
@@ -118,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;
 
@@ -205,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 });
@@ -277,6 +316,7 @@ class RecoveringCore extends EventEmitter {
 
       this._model = model;
       this._attempt = 0;
+      this._connectedOnce = true;
       this._bindModel(model);
       this._resolveInitialConnection();
       this._resolvePendingWaiters(model);
@@ -296,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 });
@@ -314,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(() => {});
   }

package/package.json

@@ -2,7 +2,7 @@
   "name": "amqplib",
   "homepage": "http://amqp-node.github.io/amqplib/",
   "main": "./channel_api.js",
-  "version": "2.1.0",
+  "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;
 
@@ -224,6 +519,108 @@ describe('recovery', () => {
     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 = [];
@@ -240,7 +637,7 @@ describe('recovery', () => {
         return Promise.resolve(new FakePromiseModel(++opened));
       }
 
-      const client = await recovery.connectWithRecoveryPromise(openModel, {waitForConnect: false});
+      const client = await recovery.connectWithRecoveryPromise(openModel, { waitForConnect: false });
 
       assert.equal(0, opened);
 
@@ -288,7 +685,7 @@ describe('recovery', () => {
         return Promise.resolve(new FakePromiseModel(1));
       }
 
-      const client = await recovery.connectWithRecoveryPromise(openModel, {waitForConnect: false});
+      const client = await recovery.connectWithRecoveryPromise(openModel, { waitForConnect: false });
       const connected = await client.waitForConnect();
 
       assert.strictEqual(client, connected);
@@ -333,8 +730,8 @@ describe('recovery', () => {
 
       await client.close();
 
-      await assert.rejects(pendingChannel, {message: 'Connection closed'});
-      await assert.rejects(client.waitForConnect(), {message: 'Connection closed'});
+      await assert.rejects(pendingChannel, { message: 'Connection closed' });
+      await assert.rejects(client.waitForConnect(), { message: 'Connection closed' });
 
       releaseOpen();
       await new Promise((resolve) => setImmediate(resolve));
@@ -366,7 +763,7 @@ describe('recovery', () => {
       assert.equal('connect failed', err.message);
       assert.equal(2, attempts);
 
-      await assert.rejects(client.waitForConnect(), {message: 'connect failed'});
+      await assert.rejects(client.waitForConnect(), { message: 'connect failed' });
       await new Promise((resolve) => setImmediate(resolve));
       assert.deepEqual([], rejections);
 
@@ -381,7 +778,7 @@ describe('recovery', () => {
       }
 
       const failures = [];
-      const client = recovery.connectWithRecoveryCallback(openModel, {waitForConnect: false}, (err, c) => {
+      const client = recovery.connectWithRecoveryCallback(openModel, { waitForConnect: false }, (err, c) => {
         if (err) return done(err);
         assert.strictEqual(client, c);
         assert.equal(0, opened);

package/.claude/settings.local.json

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