feat(sentinel): emit connect/ready/reconnecting/end lifecycle events

docs/sentinel.md

@@ -85,6 +85,32 @@ const sentinel = await createSentinel({
 | passthroughClientErrorEvents | `false` | When `true`, error events from client instances inside the sentinel will be propagated to the sentinel instance. This allows handling all client errors through a single error handler on the sentinel instance.                                                                                                     |
 | reserveClient              | `false`   | When `true`, one client will be reserved for the sentinel object. When `false`, the sentinel object will wait for the first available client from the pool.                                                                                                                                                           |
 
+## Events
+
+The sentinel object is an `EventEmitter` and emits the following lifecycle events, tracking its own `isOpen`/`isReady` state (see [`client.isReady`](../README.md#events) for the standalone client equivalents):
+
+| Name           | When                                                                                                | Listener arguments |
+| -------------- | --------------------------------------------------------------------------------------------------- | ------------------ |
+| `connect`      | The sentinel starts opening a connection (`isOpen` becomes `true`)                                  | _No arguments_     |
+| `ready`        | The sentinel has discovered the topology and is ready to accept commands (`isReady` becomes `true`) | _No arguments_     |
+| `reconnecting` | The monitored master actually changed, so the sentinel is reconfiguring and momentarily not ready (`isReady` becomes `false`). Not emitted for routine topology scans that change nothing. | _No arguments_     |
+| `end`          | The connection has been closed via `close()` or `destroy()` (`isOpen` becomes `false`)              | _No arguments_     |
+| `error`        | An error on the sentinel itself (e.g. topology discovery failed, or a `ready`/`reconnecting` listener threw). Errors from the underlying master/replica/sentinel clients are included here **only when** [`passthroughClientErrorEvents: true`](#createsentinel-configuration); otherwise they are not surfaced on the sentinel object. May be a formatted string rather than an `Error`. | `(error: Error \| string)` |
+| `topology-change` | The monitored topology changed (master/replica added, removed, or promoted)                      | `(event: RedisSentinelEvent)` |
+
+```javascript
+sentinel
+  .on('connect', () => console.log('sentinel connecting'))
+  .on('ready', () => console.log('sentinel ready'))
+  .on('reconnecting', () => console.log('sentinel reconfiguring after a topology change'))
+  .on('end', () => console.log('sentinel closed'))
+  .on('error', err => console.error('Redis Sentinel Error', err));
+```
+
+> :warning: You **MUST** listen to `error` events. Without at least one `error` listener, an emitted error is thrown and crashes the process.
+
+**Divergence from the standalone client:** these events track the sentinel facade's own state, not the sockets of the individual master/replica node clients. `reconnecting` is emitted only when the monitored master actually changes (a failover) — routine periodic topology scans that find no change are silent — and `ready` is re-emitted once the new master is connected; the per-socket reconnect churn of the underlying node clients is not surfaced. Because the sentinel abstracts failover away, a `connect`/`ready` pair is emitted once on the initial `connect()`, and `end` fires at most once even if `close()` and `destroy()` are both called. Also note that `connect` marks the start of the connection attempt (not an established socket), so a `connect()` that fails emits `connect` followed by `end` before rejecting — whereas the standalone client emits `connect` only once the socket is established: a standalone `connect()` that never reaches the server emits nothing, though it still emits `connect` before rejecting when the socket connects but initialization (e.g. authentication) fails afterwards.
+
 ## Reconnecting after an outage
 
 As the client learns the sentinel topology it discovers additional sentinel nodes (reported by the sentinels as IP addresses). The nodes you pass in `sentinelRootNodes` are kept as **seeds**: they are always retained as reconnection candidates and are tried first, alongside the discovered nodes. This matters after an outage where the whole sentinel set restarts.

packages/client/lib/sentinel/index.spec.ts

@@ -966,6 +966,33 @@ describe('legacy tests', () => {
       assert.notEqual(masterNode!.port, newMaster.port);
     });
 
+    // a failover drops readiness while reconfiguring (emits `reconnecting`) and
+    // restores it once the new topology is connected (re-emits `ready`)
+    it('emits reconnecting then ready across a failover', async function () {
+      this.timeout(60000);
+
+      sentinel = frame.getSentinelClient();
+      sentinel.setTracer(tracer);
+      sentinel.on('error', () => { });
+      await sentinel.connect();
+
+      let sawReconnecting = false;
+      let readyAfterReconnectResolve: () => void;
+      const readyAfterReconnect = new Promise<void>(res => { readyAfterReconnectResolve = res; });
+      sentinel
+        .on('reconnecting', () => { sawReconnecting = true; })
+        .on('ready', () => { if (sawReconnecting) readyAfterReconnectResolve(); });
+
+      const masterNode = sentinel.getMasterNode();
+      tracer.push(`stopping master node`);
+      await frame.stopNode(masterNode!.port.toString());
+
+      // resolves only after a `reconnecting` followed by a `ready`; otherwise the
+      // test times out, which is the failure signal we want
+      await readyAfterReconnect;
+      assert.ok(sawReconnecting);
+    });
+
     // if master changes, client should make sure user knows watches are invalid
     it('watch across master change', async function () {
       this.timeout(60000);

packages/client/lib/sentinel/index.ts

@@ -367,6 +367,13 @@ export default class RedisSentinel<
     this.#internal = new RedisSentinelInternal<M, F, S, RESP, TYPE_MAPPING>(options, this.#identity.id);
     this.#internal.on('error', err => this.emit('error', err));
 
+    /* forward the lifecycle events the internal emits from its open/ready transitions */
+    this.#internal
+      .on('connect', () => this.emit('connect'))
+      .on('ready', () => this.emit('ready'))
+      .on('reconnecting', () => this.emit('reconnecting'))
+      .on('end', () => this.emit('end'));
+
     /* pass through underling events */
     /* TODO: perhaps make this a struct and one vent, instead of multiple events */
     this.#internal.on('topology-change', (event: RedisSentinelEvent) => {
@@ -564,11 +571,31 @@ export default class RedisSentinel<
   multi = this.MULTI;
 
   async close() {
-    return this._self.#internal.close();
+    try {
+      await this._self.#internal.close();
+    } finally {
+      // In a finally: internal teardown completes even when an `end` listener
+      // throws, and the lease must not be stranded in that case either.
+      this._self.#releaseReservedLease();
+    }
+  }
+
+  async destroy() {
+    try {
+      await this._self.#internal.destroy();
+    } finally {
+      this._self.#releaseReservedLease();
+    }
   }
 
-  destroy() {
-    return this._self.#internal.destroy();
+  // The reserved lease's slot must go back to the pool queue (it is only filled at
+  // construction), otherwise a reopening connect() with reserveClient waits forever
+  // for a free client.
+  #releaseReservedLease() {
+    if (this.#reservedClientInfo) {
+      this.#internal.releaseClientLease(this.#reservedClientInfo);
+      this.#reservedClientInfo = undefined;
+    }
   }
 
   async SUBSCRIBE<T extends boolean = false>(
@@ -780,6 +807,44 @@ export class RedisSentinelInternal<
     return this.#isReady;
   }
 
+  /**
+   * Single source of truth for the `#isOpen` transition. Emits `connect` when the
+   * sentinel opens and `end` when it closes, once per real transition, so repeated
+   * `close()`/`destroy()` calls fire `end` at most once.
+   */
+  #setOpen(value: boolean) {
+    if (this.#isOpen === value) return;
+    this.#isOpen = value;
+    this.emit(value ? 'connect' : 'end');
+  }
+
+  /**
+   * Single source of truth for the `#isReady` transition. Emits `ready` when the
+   * sentinel becomes ready. A readiness drop while still open and not tearing down
+   * (an actual topology reconfigure — see `transform()`) emits `reconnecting`; a
+   * drop from `close()`/`destroy()` is silent because `#destroy` is set first.
+   */
+  #setReady(value: boolean) {
+    if (this.#isReady === value) return;
+    // Never flip to ready while tearing down: close()/destroy() set #destroy first,
+    // so an in-flight connect that resolves afterwards stays not-ready and does not
+    // emit `ready` after `end`.
+    if (value && this.#destroy) return;
+    this.#isReady = value;
+    // Route listener exceptions to `error`: these emits fire inside #connect()'s
+    // topology-retry loop, where a throwing listener would otherwise be mistaken
+    // for a discovery failure and silently swallowed by the retry.
+    try {
+      if (value) {
+        this.emit('ready');
+      } else if (this.#isOpen && !this.#destroy) {
+        this.emit('reconnecting');
+      }
+    } catch (err) {
+      this.emit('error', err);
+    }
+  }
+
   readonly #name: string;
   readonly #sentinelClientId: string;
   readonly #nodeClientOptions: RedisClientOptions<M, F, S, RESP, TYPE_MAPPING, RedisTcpSocketOptions>;
@@ -818,6 +883,7 @@ export class RedisSentinelInternal<
   }
 
   #connectPromise?: Promise<void>;
+  #teardownPromise?: Promise<void>;
   #maxCommandRediscovers: number;
   readonly #pubSubProxy: PubSubProxy;
 
@@ -988,22 +1054,29 @@ export class RedisSentinelInternal<
       throw new Error("already attempting to open")
     }
 
+    // Assign #connectPromise before emitting `connect`, so a listener that calls
+    // close()/destroy() from within the event awaits the in-flight attempt instead
+    // of tearing down before it starts. Readiness (and `ready`) is set by #connect().
+    const connectPromise = this.#connect();
     try {
-      this.#isOpen = true;
-
-      this.#connectPromise = this.#connect();
-      await this.#connectPromise;
-      this.#isReady = true;
+      this.#connectPromise = connectPromise;
+      this.#setOpen(true);
+      await connectPromise;
     } catch (err) {
       // The initial connect gave up. Tear down whatever was created along the
       // way: clients whose first connection attempt failed keep reconnecting
       // per their `reconnectStrategy`, and would otherwise stay alive in the
       // background (holding sockets and timers) after `connect()` rejected.
-      this.#connectPromise = undefined;
+      // Keep #connectPromise assigned so destroy() awaits the attempt — it is
+      // still in flight when a `connect` listener threw; the finally clears it.
       await this.destroy();
       throw err;
     } finally {
-      this.#connectPromise = undefined;
+      // Clear only if still ours: an `end` listener may have started a reentrant
+      // connect() whose in-flight promise must stay tracked for close()/destroy().
+      if (this.#connectPromise === connectPromise) {
+        this.#connectPromise = undefined;
+      }
       if (this.#isReady && this.#scanInterval > 0) {
         this.#scanTimer = setInterval(this.#resetInBackground.bind(this), this.#scanInterval);
       }
@@ -1027,6 +1100,11 @@ export class RedisSentinelInternal<
           continue;
         }
 
+        // Topology is connected: (re)assert readiness. Emits `ready` only on a real
+        // transition, so an initial connect and the tail of a failover both emit it,
+        // while a healthy periodic scan that changed nothing stays silent.
+        this.#setReady(true);
+
         this.#trace("#connect: returning");
         return;
       } catch (e) {
@@ -1127,22 +1205,35 @@ export class RedisSentinelInternal<
 
   async #reset() {
     /* closing / don't reset */
-    if (this.#isReady == false || this.#destroy == true) {
+    if (this.#destroy == true) {
       return;
     }
 
-    // already in #connect()
+    // Coalesce with an in-flight connect/reset BEFORE the gate below, so a control
+    // event arriving mid-reconfigure still registers via `#anotherReset` and the
+    // running `#connect()` re-observes the newest topology.
     if (this.#connectPromise !== undefined) {
       this.#anotherReset = true;
       return await this.#connectPromise;
     }
 
+    // Gate on #isOpen, not #isReady: a failover (or a failed one) may have left
+    // readiness false, and later control events must still be able to retry and
+    // eventually re-emit `ready`. #isReady is owned by #connect()/transform(), so a
+    // failed reconfigure honestly stays not-ready rather than falsely reporting ready.
+    if (this.#isOpen == false) {
+      return;
+    }
+
+    const connectPromise = this.#connect();
     try {
-      this.#connectPromise = this.#connect();
-      return await this.#connectPromise;
+      this.#connectPromise = connectPromise;
+      return await connectPromise;
     } finally {
       this.#trace("finished reconfgure");
-      this.#connectPromise = undefined;
+      if (this.#connectPromise === connectPromise) {
+        this.#connectPromise = undefined;
+      }
     }
   }
 
@@ -1174,14 +1265,34 @@ export class RedisSentinelInternal<
     this.#resetInBackground();
   }
 
+  /**
+   * Serializes teardown: overlapping close()/destroy() calls join the in-flight
+   * teardown instead of running a second pass over already-emptied client arrays —
+   * a second pass would emit `end` early and let the tail of the first pass kill a
+   * sentinel that a listener has since reopened.
+   */
   async close() {
+    if (this.#teardownPromise === undefined) {
+      const teardown: Promise<void> = this.#doClose().finally(() => {
+        // Guarded like #connectPromise in connect(): an `end` listener may have
+        // started a new teardown generation that must not be wiped.
+        if (this.#teardownPromise === teardown) {
+          this.#teardownPromise = undefined;
+        }
+      });
+      this.#teardownPromise = teardown;
+    }
+    return this.#teardownPromise;
+  }
+
+  async #doClose() {
     this.#destroy = true;
 
     if (this.#connectPromise != undefined) {
       await this.#connectPromise.catch(() => undefined);
     }
 
-    this.#isReady = false;
+    this.#setReady(false);
 
     this.#clientSideCache?.onPoolClose();
 
@@ -1219,19 +1330,39 @@ export class RedisSentinelInternal<
 
     this.#pubSubProxy.destroy();
 
-    this.#isOpen = false;
+    // Clear #destroy before emitting `end` (via #setOpen) and before returning, so a
+    // later connect() — or a reentrant connect() from an `end` listener — is not left
+    // half-open by #connect()'s teardown guard. Mirrors destroy(). Also start a new
+    // teardown generation: a close()/destroy() from inside the emit must tear down a
+    // reentrantly reopened sentinel, not join this already-finished pass.
+    this.#destroy = false;
+    this.#teardownPromise = undefined;
+    this.#setOpen(false);
+  }
+
+  // Coalesces with an in-flight close()/destroy() — see close() above.
+  async destroy() {
+    if (this.#teardownPromise === undefined) {
+      const teardown: Promise<void> = this.#doDestroy().finally(() => {
+        if (this.#teardownPromise === teardown) {
+          this.#teardownPromise = undefined;
+        }
+      });
+      this.#teardownPromise = teardown;
+    }
+    return this.#teardownPromise;
   }
 
   // destroy has to be async because its stopping others async events, timers and the like
   // and shouldn't return until its finished.
-  async destroy() {
+  async #doDestroy() {
     this.#destroy = true;
 
     if (this.#connectPromise != undefined) {
       await this.#connectPromise.catch(() => undefined);
     }
 
-    this.#isReady = false;
+    this.#setReady(false);
 
     this.#clientSideCache?.onPoolClose();
 
@@ -1263,8 +1394,12 @@ export class RedisSentinelInternal<
 
     this.#pubSubProxy.destroy();
 
-    this.#isOpen = false
+    // Clear #destroy before emitting `end` (via #setOpen), so a reentrant connect()
+    // from an `end` listener sees teardown finalized and can reopen cleanly. Also
+    // start a new teardown generation — see #doClose().
     this.#destroy = false;
+    this.#teardownPromise = undefined;
+    this.#setOpen(false);
   }
 
   async subscribe<T extends boolean = false>(
@@ -1482,6 +1617,12 @@ export class RedisSentinelInternal<
 
     if (analyzed.masterToOpen) {
       this.#trace(`transform: opening a new master`);
+      // The master actually changed (analyze() leaves masterToOpen undefined otherwise).
+      // If the sentinel was already running and ready, it is now reconfiguring: drop
+      // readiness (emits `reconnecting`). #connect() re-asserts readiness (emits `ready`)
+      // once the new topology is connected. On the initial connect `#isReady` is still
+      // false, so this is a no-op and no `reconnecting` is emitted.
+      this.#setReady(false);
       const masterPromises = [];
       const masterWatches: Array<boolean> = [];