Cluster Allocation Explain API Throws IAE

Throws an Illegal Argument Exception when a non-integer value is passed
as the `shard` parameter. The legacy behaviour of allowing strings to be
 passed, providing they are strings containing integers, is maintained.

Author: joshua-adams-1

rest-api-spec/src/yamlRestTest/resources/rest-api-spec/test/cluster.allocation_explain/10_basic.yml

@@ -39,7 +39,7 @@
         body: { "index": "test", "shard": 2147483647, "primary": true }
 
 ---
-"cluster shard allocation explanation test with long shard value":
+"cluster shard allocation explanation test with an invalid, string shard parameter in the body":
   - do:
       indices.create:
         index: test
@@ -49,33 +49,107 @@
   - do:
       catch: /x_content_parse_exception/
       cluster.allocation_explain:
-        body: { "index": "test", "shard": 214748364777, "primary": true }
+        body: { "index": "test", "shard": "wrong", "primary": true }
 
 ---
-"cluster shard allocation explanation test with float shard value":
+"cluster shard allocation explanation test with a valid, string shard parameter in the body":
   - do:
       indices.create:
         index: test
-        body: { "settings": { "index.number_of_shards": 2, "index.number_of_replicas": 0 } }
 
   - match: { acknowledged: true }
 
   - do:
       cluster.allocation_explain:
-        body: { "index": "test", "shard": 1.0, "primary": true }
+        body: { "index": "test", "shard": "0", "primary": true }
 
   - match: { current_state: "started" }
   - is_true: current_node.id
   - match: { index: "test" }
-  - match: { shard: 1 }
+  - match: { shard: 0 }
   - match: { primary: true }
   - is_true: can_remain_on_current_node
   - is_true: can_rebalance_cluster
   - is_true: can_rebalance_to_other_node
   - is_true: rebalance_explanation
 
+---
+"cluster shard allocation explanation test with long shard value":
+  - requires:
+      capabilities:
+        - method: GET
+          path: /_cluster/allocation/explain
+          capabilities: [shard_parameter_non_integer_validation]
+      test_runner_features: [capabilities]
+      reason: Additional validation for the shard parameter was added in 9.2.0
+
+  - do:
+      indices.create:
+        index: test
+
+  - match: { acknowledged: true }
+
+  - do:
+      catch: /x_content_parse_exception/
+      cluster.allocation_explain:
+        body: { "index": "test", "shard": 214748364777, "primary": true }
+
+---
+"cluster shard allocation explanation test with float shard value":
+  - requires:
+      capabilities:
+        - method: GET
+          path: /_cluster/allocation/explain
+          capabilities: [ shard_parameter_non_integer_validation ]
+      test_runner_features: [ capabilities ]
+      reason: Additional validation for the shard parameter was added in 9.2.0
+
+  - do:
+      indices.create:
+        index: test
+        body: { "settings": { "index.number_of_shards": 2, "index.number_of_replicas": 0 } }
+
+  - match: { acknowledged: true }
+
+  - do:
+      catch: /illegal_argument_exception/
+      cluster.allocation_explain:
+        body: { "index": "test", "shard": 1.0, "primary": true }
+
+---
+"cluster shard allocation explanation test with stringified float shard value":
+  - requires:
+      capabilities:
+        - method: GET
+          path: /_cluster/allocation/explain
+          capabilities: [ shard_parameter_non_integer_validation ]
+      test_runner_features: [ capabilities ]
+      reason: Additional validation for the shard parameter was added in 9.2.0
+
+
+  - do:
+      indices.create:
+        index: test
+        body: { "settings": { "index.number_of_shards": 2, "index.number_of_replicas": 0 } }
+
+  - match: { acknowledged: true }
+
+  - do:
+      catch: /illegal_argument_exception/
+      cluster.allocation_explain:
+        body: { "index": "test", "shard": "1.0", "primary": true }
+
+
 ---
 "cluster shard allocation explanation test with double shard value":
+  - requires:
+      capabilities:
+        - method: GET
+          path: /_cluster/allocation/explain
+          capabilities: [ shard_parameter_non_integer_validation ]
+      test_runner_features: [ capabilities ]
+      reason: Additional validation for the shard parameter was added in 9.2.0
+
   - do:
       indices.create:
         index: test
@@ -84,18 +158,32 @@
   - match: { acknowledged: true }
 
   - do:
+      catch: /x_content_parse_exception/
       cluster.allocation_explain:
         body: { "index": "test", "shard": 1.1234567891234567, "primary": true }
 
-  - match: { current_state: "started" }
-  - is_true: current_node.id
-  - match: { index: "test" }
-  - match: { shard: 1 }
-  - match: { primary: true }
-  - is_true: can_remain_on_current_node
-  - is_true: can_rebalance_cluster
-  - is_true: can_rebalance_to_other_node
-  - is_true: rebalance_explanation
+---
+"cluster shard allocation explanation test with stringified double shard value":
+  - requires:
+      capabilities:
+        - method: GET
+          path: /_cluster/allocation/explain
+          capabilities: [ shard_parameter_non_integer_validation ]
+      test_runner_features: [ capabilities ]
+      reason: Additional validation for the shard parameter was added in 9.2.0
+
+  - do:
+      indices.create:
+        index: test
+        body: { "settings": { "index.number_of_shards": 2, "index.number_of_replicas": 0 } }
+
+  - match: { acknowledged: true }
+
+  - do:
+      catch: /x_content_parse_exception/
+      cluster.allocation_explain:
+        body: { "index": "test", "shard": "1.1234567891234567", "primary": true }
+
 
 ---
 "cluster shard allocation explanation test with three valid body parameters":

server/src/main/java/org/elasticsearch/action/admin/cluster/allocation/ClusterAllocationExplainRequest.java

@@ -31,7 +31,34 @@ public class ClusterAllocationExplainRequest extends MasterNodeRequest<ClusterAl
     private static final ObjectParser<ClusterAllocationExplainRequest, Void> PARSER = new ObjectParser<>("cluster/allocation/explain");
     static {
         PARSER.declareString(ClusterAllocationExplainRequest::setIndex, new ParseField("index"));
-        PARSER.declareInt(ClusterAllocationExplainRequest::setShard, new ParseField("shard"));
+        PARSER.declareField(
+            ClusterAllocationExplainRequest::setShard,
+            (xContentParser) -> {
+                if (xContentParser.currentToken() == XContentParser.Token.VALUE_NUMBER) {
+                    if (xContentParser.numberType() == XContentParser.NumberType.INT) {
+                        return xContentParser.intValue();
+                    } else {
+                        throw new IllegalArgumentException("Expected an integer value for [shard]");
+                    }
+                } else if (xContentParser.currentToken() == XContentParser.Token.VALUE_STRING) {
+                    String text = xContentParser.text();
+                    try {
+                        // Only accept if the string is a valid integer representation
+                        if (text.matches("[-+]?\\d+")) {
+                            return Integer.parseInt(text);
+                        } else {
+                            throw new IllegalArgumentException("String value for [shard] must be an integer, but was: " + text);
+                        }
+                    } catch (NumberFormatException e) {
+                        throw new IllegalArgumentException("Invalid integer value for [shard]: " + text, e);
+                    }
+                } else {
+                    throw new IllegalArgumentException("Expected an integer for [shard]");
+                }
+            },
+            new ParseField("shard"),
+            ObjectParser.ValueType.INT
+        );
         PARSER.declareBoolean(ClusterAllocationExplainRequest::setPrimary, new ParseField("primary"));
         PARSER.declareString(ClusterAllocationExplainRequest::setCurrentNode, new ParseField("current_node"));
     }

server/src/main/java/org/elasticsearch/rest/action/admin/cluster/RestClusterAllocationExplainAction.java

@@ -22,6 +22,7 @@
 
 import java.io.IOException;
 import java.util.List;
+import java.util.Set;
 
 import static org.elasticsearch.rest.RestRequest.Method.GET;
 import static org.elasticsearch.rest.RestRequest.Method.POST;
@@ -47,6 +48,11 @@ public boolean allowSystemIndexAccessByDefault() {
         return true;
     }
 
+    @Override
+    public Set<String> supportedCapabilities() {
+        return Set.of("shard_parameter_non_integer_validation");
+    }
+
     @Override
     public RestChannelConsumer prepareRequest(final RestRequest request, final NodeClient client) throws IOException {
         final var req = new ClusterAllocationExplainRequest(RestUtils.getMasterNodeTimeout(request));