fix(client): update HOTKEYS commands to match latest server API

* chore(tests): update test container to custom-21651605017-debian-amd64

* fix(client): update HOTKEYS commands to match latest server API

- Change time units from ms to us for CPU time fields
- Add SlotRange interface for slot range representation
- Update field names (byCpuTime → byCpuTimeUs, etc.)
- Fix HOTKEYS_STOP to return null in empty state
- Update response parsing for new array-wrapped format
- Add test for HOTKEYS_STOP empty state behavior
- nil -> null

* fix(client): exclude HOTKEYS commands from cluster, pool, and sentinel clients

HOTKEYS commands require session affinity (sticky connection to a single
Redis node) which cluster, pool, and sentinel clients cannot guarantee.

Changes:
- Created NON_STICKY_COMMANDS export in commands/index.ts that excludes HOTKEYS commands
- Updated cluster, pool, and sentinel to use NON_STICKY_COMMANDS instead of COMMANDS
- Added tests to verify HOTKEYS commands are not available on these client types

* chore(tests): update test container to custom-21860421418-debian-amd64

* fix(hotkeys): update field name to sampled-commands-selected-slots-us

- Fix field name from 'sampled-command-selected-slots-us' to
  'sampled-commands-selected-slots-us' (with 's') to align with
  server changes in the new test image
- Update TypeScript property name from sampledCommandSelectedSlotsUs
  to sampledCommandsSelectedSlotsUs for consistency
- Add comprehensive tests for all HOTKEYS GET response fields
- Add cluster tests for SLOTS and SAMPLE options to verify
  slot-specific and sampled fields are correctly parsed

Author: nkaradzhov

.github/workflows/tests.yml

@@ -29,7 +29,7 @@ jobs:
             version: "8.2"
           - tag: "8.4.0"
             version: "8.4"
-          - tag: "custom-21183968220-debian-amd64"
+          - tag: "custom-21860421418-debian-amd64"
             version: "8.6"
     steps:
       - uses: actions/checkout@v4

packages/bloom/lib/test-utils.ts

@@ -5,7 +5,7 @@ export default  TestUtils.createFromConfig({
   dockerImageName: 'redislabs/client-libs-test',
   dockerImageTagArgument: 'redis-tag',
   dockerImageVersionArgument: 'redis-version',
-  defaultDockerVersion: { tag: 'custom-21183968220-debian-amd64', version: '8.6' }
+  defaultDockerVersion: { tag: 'custom-21860421418-debian-amd64', version: '8.6' }
 });
 
 export const GLOBAL = {

packages/client/lib/client/pool.spec.ts

@@ -1,7 +1,21 @@
 import { strict as assert } from 'node:assert';
 import testUtils, { GLOBAL } from '../test-utils';
+import { RedisClientPool } from './pool';
 
 describe('RedisClientPool', () => {
+  it('should not have HOTKEYS commands (requires session affinity)', () => {
+    // HOTKEYS commands require session affinity and are only available on standalone clients
+    const pool = RedisClientPool.create({});
+    assert.equal((pool as any).hotkeysStart, undefined);
+    assert.equal((pool as any).hotkeysStop, undefined);
+    assert.equal((pool as any).hotkeysGet, undefined);
+    assert.equal((pool as any).hotkeysReset, undefined);
+    assert.equal((pool as any).HOTKEYS_START, undefined);
+    assert.equal((pool as any).HOTKEYS_STOP, undefined);
+    assert.equal((pool as any).HOTKEYS_GET, undefined);
+    assert.equal((pool as any).HOTKEYS_RESET, undefined);
+  });
+
   testUtils.testWithClientPool('sendCommand', async pool => {
     assert.equal(
       await pool.sendCommand(['PING']),

packages/client/lib/client/pool.ts

@@ -1,6 +1,6 @@
-import COMMANDS from '../commands';
-import { Command, RedisArgument, RedisFunction, RedisFunctions, RedisModules, RedisScript, RedisScripts, RespVersions, TypeMapping } from '../RESP/types';
-import RedisClient, { RedisClientType, RedisClientOptions, RedisClientExtensions } from '.';
+import { NON_STICKY_COMMANDS } from '../commands';
+import { Command, CommandSignature, RedisArgument, RedisFunction, RedisFunctions, RedisModules, RedisScript, RedisScripts, RespVersions, TypeMapping } from '../RESP/types';
+import RedisClient, { RedisClientType, RedisClientOptions, WithModules, WithFunctions, WithScripts } from '.';
 import { EventEmitter } from 'node:events';
 import { DoublyLinkedNode, DoublyLinkedList, SinglyLinkedList } from './linked-list';
 import { TimeoutError } from '../errors';
@@ -88,6 +88,14 @@ export type PoolTask<
   T = unknown
 > = (client: RedisClientType<M, F, S, RESP, TYPE_MAPPING>) => T;
 
+// Pool uses NON_STICKY_COMMANDS to exclude commands that require session affinity (like HOTKEYS)
+type PoolWithCommands<
+  RESP extends RespVersions,
+  TYPE_MAPPING extends TypeMapping
+> = {
+  [P in keyof typeof NON_STICKY_COMMANDS]: CommandSignature<(typeof NON_STICKY_COMMANDS)[P], RESP, TYPE_MAPPING>;
+};
+
 export type RedisClientPoolType<
   M extends RedisModules = {},
   F extends RedisFunctions = {},
@@ -96,7 +104,10 @@ export type RedisClientPoolType<
   TYPE_MAPPING extends TypeMapping = {}
 > = (
   RedisClientPool<M, F, S, RESP, TYPE_MAPPING> &
-  RedisClientExtensions<M, F, S, RESP, TYPE_MAPPING>
+  PoolWithCommands<RESP, TYPE_MAPPING> &
+  WithModules<M, RESP, TYPE_MAPPING> &
+  WithFunctions<F, RESP, TYPE_MAPPING> &
+  WithScripts<S, RESP, TYPE_MAPPING>
 );
 
 type ProxyPool = RedisClientPoolType<any, any, any, any, any>;
@@ -174,7 +185,7 @@ export class RedisClientPool<
     if(!Pool) {
       Pool = attachConfig({
         BaseClass: RedisClientPool,
-        commands: COMMANDS,
+        commands: NON_STICKY_COMMANDS,
         createCommand: RedisClientPool.#createCommand,
         createModuleCommand: RedisClientPool.#createModuleCommand,
         createFunctionCommand: RedisClientPool.#createFunctionCommand,

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

@@ -7,6 +7,19 @@ import { spy } from 'sinon';
 import RedisClient from '../client';
 
 describe('Cluster', () => {
+  it('should not have HOTKEYS commands (requires session affinity)', () => {
+    // HOTKEYS commands require session affinity and are only available on standalone clients
+    const cluster = RedisCluster.create({ rootNodes: [] });
+    assert.equal((cluster as any).hotkeysStart, undefined);
+    assert.equal((cluster as any).hotkeysStop, undefined);
+    assert.equal((cluster as any).hotkeysGet, undefined);
+    assert.equal((cluster as any).hotkeysReset, undefined);
+    assert.equal((cluster as any).HOTKEYS_START, undefined);
+    assert.equal((cluster as any).HOTKEYS_STOP, undefined);
+    assert.equal((cluster as any).HOTKEYS_GET, undefined);
+    assert.equal((cluster as any).HOTKEYS_RESET, undefined);
+  });
+
   testUtils.testWithCluster('sendCommand', async cluster => {
     assert.equal(
       await cluster.sendCommand(undefined, true, ['PING']),

packages/client/lib/cluster/index.ts

@@ -1,7 +1,7 @@
-import { RedisClientOptions, RedisClientType } from '../client';
+import { RedisClientOptions, RedisClientType, WithFunctions, WithModules, WithScripts } from '../client';
 import { CommandOptions } from '../client/commands-queue';
-import { Command, CommandArguments, CommanderConfig, TypeMapping, RedisArgument, RedisFunction, RedisFunctions, RedisModules, RedisScript, RedisScripts, ReplyUnion, RespVersions } from '../RESP/types';
-import COMMANDS from '../commands';
+import { Command, CommandArguments, CommanderConfig, CommandSignature, TypeMapping, RedisArgument, RedisFunction, RedisFunctions, RedisModules, RedisScript, RedisScripts, ReplyUnion, RespVersions } from '../RESP/types';
+import { NON_STICKY_COMMANDS } from '../commands';
 import { EventEmitter } from 'node:events';
 import { attachConfig, functionArgumentsPrefix, getTransformReply, scriptArgumentsPrefix } from '../commander';
 import RedisClusterSlots, { NodeAddressMap, ShardNode } from './cluster-slots';
@@ -13,7 +13,13 @@ import { ClientSideCacheConfig, PooledClientSideCacheProvider } from '../client/
 import { BasicCommandParser } from '../client/parser';
 import { ASKING_CMD } from '../commands/ASKING';
 import SingleEntryCache from '../single-entry-cache'
-import { WithCommands, WithFunctions, WithModules, WithScripts } from '../client';
+
+type WithCommands<
+  RESP extends RespVersions,
+  TYPE_MAPPING extends TypeMapping
+> = {
+  [P in keyof typeof NON_STICKY_COMMANDS]: CommandSignature<(typeof NON_STICKY_COMMANDS)[P], RESP, TYPE_MAPPING>;
+};
 
 interface ClusterCommander<
   M extends RedisModules,
@@ -222,7 +228,7 @@ export default class RedisCluster<
     if (!Cluster) {
       Cluster = attachConfig({
         BaseClass: RedisCluster,
-        commands: COMMANDS,
+        commands: NON_STICKY_COMMANDS,
         createCommand: RedisCluster.#createCommand,
         createModuleCommand: RedisCluster.#createModuleCommand,
         createFunctionCommand: RedisCluster.#createFunctionCommand,

packages/client/lib/cluster/multi-command.ts

@@ -1,4 +1,4 @@
-import COMMANDS from '../commands';
+import { NON_STICKY_COMMANDS } from '../commands';
 import RedisMultiCommand, { MULTI_REPLY, MultiReply, MultiReplyType, RedisMultiQueuedCommand } from '../multi-command';
 import { ReplyWithTypeMapping, CommandReply, Command, CommandArguments, CommanderConfig, RedisFunctions, RedisModules, RedisScripts, RespVersions, TransformReply, RedisScript, RedisFunction, TypeMapping, RedisArgument } from '../RESP/types';
 import { attachConfig, functionArgumentsPrefix, getTransformReply } from '../commander';
@@ -30,7 +30,7 @@ type WithCommands<
   RESP extends RespVersions,
   TYPE_MAPPING extends TypeMapping
 > = {
-  [P in keyof typeof COMMANDS]: CommandSignature<REPLIES, (typeof COMMANDS)[P], M, F, S, RESP, TYPE_MAPPING>;
+  [P in keyof typeof NON_STICKY_COMMANDS]: CommandSignature<REPLIES, (typeof NON_STICKY_COMMANDS)[P], M, F, S, RESP, TYPE_MAPPING>;
 };
 
 type WithModules<
@@ -183,7 +183,7 @@ export default class RedisClusterMultiCommand<REPLIES = []> {
   >(config?: CommanderConfig<M, F, S, RESP>) {
     return attachConfig({
       BaseClass: RedisClusterMultiCommand,
-      commands: COMMANDS,
+      commands: NON_STICKY_COMMANDS,
       createCommand: RedisClusterMultiCommand.#createCommand,
       createModuleCommand: RedisClusterMultiCommand.#createModuleCommand,
       createFunctionCommand: RedisClusterMultiCommand.#createFunctionCommand,

packages/client/lib/commands/HOTKEYS_GET.spec.ts

@@ -24,12 +24,12 @@ describe('HOTKEYS GET', () => {
     minimumDockerVersion: [8, 6]
   });
 
-  testUtils.testWithClient('client.hotkeysGet returns data during tracking', async client => {
+  testUtils.testWithClient('client.hotkeysGet returns all required fields during tracking', async client => {
     // Clean up any existing state first
     await client.hotkeysStop();
     await client.hotkeysReset();
 
-    // Start tracking
+    // Start tracking with both CPU and NET metrics
     await client.hotkeysStart({
       METRICS: { count: 2, CPU: true, NET: true }
     });
@@ -40,15 +40,24 @@ describe('HOTKEYS GET', () => {
     await client.get('testKey1');
     await client.get('testKey2');
 
-    // GET should return data
+    // GET should return data with all required fields
     const reply = await client.hotkeysGet();
-    assert.notEqual(reply, null);
+    assert.ok(reply, 'Expected reply to not be null');
+
+    // Required fields - must be present
     assert.equal(typeof reply.trackingActive, 'number');
     assert.equal(typeof reply.sampleRatio, 'number');
     assert.ok(Array.isArray(reply.selectedSlots));
+    assert.equal(typeof reply.allCommandsAllSlotsUs, 'number');
+    assert.equal(typeof reply.netBytesAllCommandsAllSlots, 'number');
     assert.equal(typeof reply.collectionStartTimeUnixMs, 'number');
     assert.equal(typeof reply.collectionDurationMs, 'number');
-    assert.ok(Array.isArray(reply.byCpuTime));
+    assert.equal(typeof reply.totalCpuTimeSysMs, 'number');
+    assert.equal(typeof reply.totalCpuTimeUserMs, 'number');
+    assert.equal(typeof reply.totalNetBytes, 'number');
+
+    // Metric arrays - present when requested
+    assert.ok(Array.isArray(reply.byCpuTimeUs));
     assert.ok(Array.isArray(reply.byNetBytes));
 
     // Stop and reset tracking to clean up
@@ -59,6 +68,87 @@ describe('HOTKEYS GET', () => {
     minimumDockerVersion: [8, 6]
   });
 
+  testUtils.testWithCluster('cluster.hotkeysGet returns slot-specific fields with SLOTS option', async cluster => {
+    const client = await cluster.nodeClient(cluster.masters[0]);
+
+    // Get the slots owned by this master node
+    const clusterSlots = await client.clusterSlots();
+    const masterSlots = clusterSlots[0]; // First slot range
+    const slotStart = masterSlots.from as number;
+    const slotEnd = Math.min(slotStart + 1, masterSlots.to as number);
+
+    // Clean up any existing state first
+    await client.hotkeysStop();
+    await client.hotkeysReset();
+
+    // Start tracking with SLOTS option using slots owned by this master
+    await client.hotkeysStart({
+      METRICS: { count: 2, CPU: true, NET: true },
+      SLOTS: { count: 2, slots: [slotStart, slotEnd] }
+    });
+
+    // Perform some operations using the cluster (which routes correctly)
+    await cluster.set('testKey1', 'value1');
+    await cluster.get('testKey1');
+
+    const reply = await client.hotkeysGet();
+    assert.ok(reply, 'Expected reply to not be null');
+
+    // When SLOTS is specified, these fields should be present
+    assert.equal(typeof reply.allCommandsSelectedSlotsUs, 'number');
+    assert.equal(typeof reply.netBytesAllCommandsSelectedSlots, 'number');
+
+    // selectedSlots should contain the specified slots
+    assert.ok(Array.isArray(reply.selectedSlots));
+    assert.ok(reply.selectedSlots.length > 0);
+
+    // Stop and reset tracking to clean up
+    await client.hotkeysStop();
+    await client.hotkeysReset();
+  }, {
+    ...GLOBAL.CLUSTERS.OPEN,
+    minimumDockerVersion: [8, 6]
+  });
+
+  testUtils.testWithCluster('cluster.hotkeysGet returns sampled fields with SAMPLE and SLOTS options', async cluster => {
+    const client = await cluster.nodeClient(cluster.masters[0]);
+
+    // Get the slots owned by this master node
+    const clusterSlots = await client.clusterSlots();
+    const masterSlots = clusterSlots[0]; // First slot range
+    const slotStart = masterSlots.from as number;
+    const slotEnd = Math.min(slotStart + 1, masterSlots.to as number);
+
+    // Clean up any existing state first
+    await client.hotkeysStop();
+    await client.hotkeysReset();
+
+    // Start tracking with SAMPLE > 1 and SLOTS using slots owned by this master
+    await client.hotkeysStart({
+      METRICS: { count: 2, CPU: true, NET: true },
+      SAMPLE: 2,
+      SLOTS: { count: 2, slots: [slotStart, slotEnd] }
+    });
+
+    // Perform some operations using the cluster (which routes correctly)
+    await cluster.set('testKey1', 'value1');
+    await cluster.get('testKey1');
+
+    const reply = await client.hotkeysGet();
+    assert.ok(reply, 'Expected reply to not be null');
+
+    // When SAMPLE > 1 AND SLOTS is specified, these fields should be present
+    assert.equal(typeof reply.sampledCommandsSelectedSlotsUs, 'number');
+    assert.equal(typeof reply.netBytesSampledCommandsSelectedSlots, 'number');
+
+    // Stop and reset tracking to clean up
+    await client.hotkeysStop();
+    await client.hotkeysReset();
+  }, {
+    ...GLOBAL.CLUSTERS.OPEN,
+    minimumDockerVersion: [8, 6]
+  });
+
   testUtils.testWithClient('client.hotkeysGet returns data after stopping', async client => {
     // Clean up any existing state first
     await client.hotkeysStop();
@@ -78,7 +168,7 @@ describe('HOTKEYS GET', () => {
 
     // GET should still return data in STOPPED state
     const reply = await client.hotkeysGet();
-    assert.notEqual(reply, null);
+    assert.ok(reply, 'Expected reply to not be null');
     // Tracking should be inactive after stop
     assert.equal(reply.trackingActive, 0);