Description

The Java client is missing support for cluster management commands. While the Python, Node.js, and Go clients have some cluster command support, the Java client currently lacks a comprehensive set of cluster operations, making it difficult to programmatically manage and monitor Valkey clusters from Java applications.

Problem Statement

Applications using the Java client cannot:

• Inspect cluster state and topology programmatically
• Manage slot allocation and migration
• Control node membership in the cluster
• Perform administrative operations like failovers
• Monitor cluster health and performance
• Scale clusters dynamically

Currently, developers must use external tools or custom commands to perform these operations, which is not ideal for production environments where programmatic cluster management is essential.

Proposed Solution

Implement the following cluster management commands in the Java client:

Cluster Information & Topology

• CLUSTER INFO - Get cluster state and statistics
• CLUSTER NODES - List all nodes with their roles and states
• CLUSTER SHARDS - Get detailed shard information with slot ranges
• CLUSTER SLOTS - Get slot-to-node mapping
• CLUSTER LINKS - View inter-node connections
• CLUSTER MYID - Get current node's unique identifier
• CLUSTER MYSHARDID - Get current node's shard identifier

Slot Management

• CLUSTER ADDSLOTS - Assign slots to nodes
• CLUSTER ADDSLOTSRANGE - Assign slot ranges to nodes
• CLUSTER DELSLOTS - Remove slot assignments
• CLUSTER DELSLOTSRANGE - Remove slot range assignments
• CLUSTER KEYSLOT - Calculate which slot a key belongs to
• CLUSTER COUNTKEYSINSLOT - Count keys in a specific slot
• CLUSTER GETKEYSINSLOT - Retrieve keys from a specific slot

Node Management

• CLUSTER MEET - Add a new node to the cluster
• CLUSTER FORGET - Remove a node from the cluster
• CLUSTER REPLICATE - Configure replication between nodes
• CLUSTER REPLICAS - List replicas of a specific node
• CLUSTER COUNT-FAILURE-REPORTS - Get failure report count for a node

Cluster Operations

• CLUSTER FAILOVER - Trigger manual failover
• CLUSTER SETSLOT - Manage slot migration states
• CLUSTER BUMPEPOCH - Force configuration epoch increment
• CLUSTER SET-CONFIG-EPOCH - Set node's configuration epoch
• CLUSTER FLUSHSLOTS - Clear slot assignment cache
• CLUSTER RESET - Reset cluster state (SOFT and HARD options)

Connection Control

• READONLY - Enable read commands on replicas
• READWRITE - Disable read-only mode
• ASKING - Allow commands during slot migration

Admin Operations

• CLUSTER SAVECONFIG - Persist cluster configuration to disk
• CLUSTER DUMPKEYSSLOT - Get serialized key data for migration

Expected Behavior

API Design

// Simple cluster info query
String info = client.clusterInfo().get();

// Calculate slot for a key
long slot = client.clusterKeySlot("user:12345").get();

// Add slots to current node
client.clusterAddSlots(new long[]{1000, 1001, 1002}).get();

// Add a new node to cluster
client.clusterMeet("new-node.example.com", 6379).get();

// Trigger failover
ClusterFailoverOptions options = ClusterFailoverOptions.builder()
    .force(ClusterFailoverOptions.FORCE)
    .build();
client.clusterFailover(options).get();

Features Required

1. Type-safe API - Proper method signatures with appropriate parameter types
2. Multi-node routing - Support for Route parameter where applicable
3. Batch support - All commands should be available in ClusterBatch
4. Binary key support - Accept GlideString where appropriate
5. Comprehensive documentation - Javadoc with examples for each command
6. Client-side validation - Validate inputs (slots, node IDs, etc.) before server calls
7. Error handling - Clear error messages for common mistakes

Testing Requirements

• Unit tests for client-side validation logic
• Integration tests for each command
• Multi-node routing tests
• Batch operation tests
• Concurrent execution tests
• Error handling tests

Acceptance Criteria

• All 30 cluster commands are implemented in GlideClusterClient
• New ClusterCommands interface is created with proper signatures
• All commands support multi-node routing where applicable
• Batch support is added to ClusterBatch for all commands
• Client-side validation is implemented for parameters (slots, node IDs, ports, etc.)
• Comprehensive Javadoc with examples for each command
• Integration tests with >90% coverage
• All tests pass in CI/CD
• CHANGELOG.md is updated
• No breaking changes to existing APIs

Additional Context

Current State

• Python client: Has most cluster commands implemented
• Node.js client: Has cluster command support
• Go client: Has cluster command support
• Java client: Missing cluster commands (this issue)

References

• Valkey Cluster Commands Documentation
• Redis Cluster Specification
• Jedis implementation: Has cluster commands
• Lettuce implementation: Has cluster commands

Priority

High - This is a critical gap for Java applications that need programmatic cluster management. Without these commands, Java users cannot effectively manage production clusters.

Labels

• enhancement
• java
• cluster
• good first issue (if broken into smaller tasks)

Environment:

• Valkey GLIDE Version: main branch
• Java Version: 11+
• OS: All platforms