feat(cluster): support custom Redis class for internal connections

[rit3sh-x]

Summary

Closes #2073.

Adds a redisClass option to ClusterOptions so users can pass a Redis subclass (e.g. class RedisWithInstrumentation extends Redis) and have it used for every internal connection the
Cluster creates.

Motivation

Users who subclass Redis for OpenTelemetry, logging, or custom error handling currently can't use their subclass with Cluster, because Cluster hardcodes new Redis(...) internally in multiple
places (pool, subscribers, slot refresher). This forces monkeypatching.

What changes

redisClass is threaded from ClusterOptions to every internal Redis construction site:

• ConnectionPool — pool node connections
• ClusterSubscriber — pub/sub subscriber
• ShardedSubscriber (via ClusterSubscriberGroup) — sharded pub/sub subscribers
• Cluster.getInfoFromNode — slot refresh connections (previously used redis.duplicate())

Defaults to Redis when not set — zero breaking changes.

Usage

class InstrumentedRedis extends Redis {
  sendCommand(command) {
    // add tracing, logging, error handling
    return super.sendCommand(command);
  }
}

const cluster = new Redis.Cluster(nodes, { redisClass: InstrumentedRedis });

Test plan

New test file test/functional/cluster/redis_class.ts with 8 behavior-focused tests:

• Default Redis class used when option not set (backward compat)
• Custom subclass used for pool node connections (multi-node)
• Constructor invoked for every connection Cluster creates
• Subscriber connections use subclass
• Sharded subscriber connections use subclass
• Slot refresh connections use subclass
• sendCommand override actually intercepts commands end-to-end
• Normal cluster functionality preserved with subclass

Full suite: 562 passing, 17 cluster passing, build + tsd pass.

Notes

• Tests verify observable behavior (instanceof, constructor side-effects, command interception), not internal wiring, so they remain valid under future refactors.
• Does not fix duplicate method should new subclasses #2053 (standalone duplicate()). That's a separate issue rooted in the Commander mixin system and warrants its own PR.

---

Note

Medium Risk
Touches core Cluster connection creation paths (pool nodes, subscribers, and slot-refresh connections), so regressions could affect connectivity and slot refresh behavior despite being opt-in. Backward compatibility is preserved by defaulting to Redis, and functional tests cover the new wiring.

Overview
Adds a new ClusterOptions.redisClass hook so a user-provided Redis subclass is used for all internal Cluster connections (node pool, subscriber, sharded subscribers, and slot refresh).

Threads redisClass through ConnectionPool, ClusterSubscriber, ShardedSubscriber/ClusterSubscriberGroup, and changes slot refresh to create a new connection via redisClass (instead of redis.duplicate()), then adds functional tests asserting default behavior and that instrumentation/overrides (e.g. sendCommand) apply end-to-end.

^{Reviewed by Cursor Bugbot for commit a51dd8c. Bugbot is set up for automated code reviews on this repo. Configure here.}

[PavelPashov]

Thanks for the PR. I will review it and follow up once I have gone through it.

[PavelPashov]

run sharded pub sub tests

[uglide]

Testcase	Errors	Failures	Skipped	Total
Root Suite	0	0	0	0
Sharded Pub/Sub E2E - Basic	0	0	0	4
Sharded Pub/Sub E2E - Connection Lifecycle	0	0	0	3
Sharded Pub/Sub E2E - Failure Recovery Multiple Subscribers	0	0	0	4
Sharded Pub/Sub E2E - Failure Recovery Single Subscriber	0	0	0	4

---- Details for maintainers

[uglide]

Testcase	Errors	Failures	Skipped	Total
Root Suite	0	0	0	0
Sharded Pub/Sub E2E - Basic	0	0	0	4
Sharded Pub/Sub E2E - Connection Lifecycle	0	0	0	3
Sharded Pub/Sub E2E - Failure Recovery Multiple Subscribers	0	0	0	4
Sharded Pub/Sub E2E - Failure Recovery Single Subscriber	0	0	0	4

---- Details for maintainers

[uglide]

Testcase	Errors	Failures	Skipped	Total
Root Suite	0	0	0	0
Sharded Pub/Sub E2E - Basic	0	0	0	4
Sharded Pub/Sub E2E - Connection Lifecycle	0	0	0	3
Sharded Pub/Sub E2E - Failure Recovery Multiple Subscribers	0	1	0	4
Sharded Pub/Sub E2E - Failure Recovery Single Subscriber	0	1	0	4

---- Details for maintainers

[rit3sh-x]

@uglide thanks for running this.

I can't access the CAE action logs from outside, could you share the failure output for the two Failure Recovery cases (Multiple Subscribers / Single Subscriber)?

I want to confirm whether this is a regression from threading redisClass through the reconnection path, or a pre-existing flake on main. If it's the PR, the most likely culprit is a missed new Redis(...) → new this.RedisClass(...) replacement somewhere in the recovery code, I'll audit that path once I see the error.

[rit3sh-x]

@PavelPashov @uglide quick update on the CAE Failure Recovery failures.

I spun up a local branch (test/2053-plus-2097) that merges this PR on top of #2053 (the applyMixin + duplicate() subclass fix). My theory was that the failure-recovery path relies on this.constructor / duplicate() behavior that was broken before #2053, so #2097 alone would be missing the foundation it needs.

What I tested, against both a local Redis cluster and a single-node instance:

On test/2053-plus-2097 (combined branch):

• Clean merge between feat(cluster): support custom Redis class for internal connections #2097 and duplicate method should new subclasses #2053 with no conflicts in lib/cluster/index.ts or elsewhere
• npm run build: clean, zero tsc errors
• test/unit/duplicate.ts (15 tests for subclass preservation): 15/15 passing
• test/functional/spub_ssub.ts (sharded pub/sub functional suite): 9/9 passing, including the auto-resubscription race-condition test

On feat/cluster-custom-redis-class alone (this PR without #2053):

• npm run build: clean
• test/functional/spub_ssub.ts: 9/9 passing, same results as the combined branch

So the local functional suite passes on both branches, which means the CAE Failure Recovery cases are exercising a code path my local tests do not cover. I cannot reproduce the CAE harness locally, so I cannot directly confirm the hypothesis from my side.

[rit3sh-x]

@PavelPashov any updates?