Deprecate the 'local' parameter of /_cat/shards (#62197)

Author: boicehuang

docs/reference/cat/shards.asciidoc

@@ -273,7 +273,10 @@ Reason the shard is unassigned. Returned values are:
 
 include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=help]
 
-include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=local]
+`local`::
+(Optional, boolean)
++
+deprecated::[7.10.0,"This parameter does not affect the request. It will be removed in a future release."]
 
 include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=master-timeout]
 
@@ -378,7 +381,7 @@ my-index-000001 0 r INITIALIZING    0 14.3mb 192.168.56.30 bGG90GE
 ===== Example with reasons for unassigned shards
 
 The following request returns the `unassigned.reason` column, which indicates
-why a shard is unassigned. 
+why a shard is unassigned.
 
 
 [source,console]

rest-api-spec/src/main/resources/rest-api-spec/api/cat.shards.json

@@ -51,7 +51,11 @@
       },
       "local":{
         "type":"boolean",
-        "description":"Return local information, do not retrieve the state from master node (default: false)"
+        "description":"Return local information, do not retrieve the state from master node (default: false)",
+        "deprecated":{
+          "version":"8.0.0",
+          "description":"This parameter does not affect the request. It will be removed in a future release."
+        }
       },
       "master_timeout":{
         "type":"time",

server/src/main/java/org/elasticsearch/rest/action/cat/RestShardsAction.java

@@ -30,6 +30,7 @@
 import org.elasticsearch.cluster.routing.UnassignedInfo;
 import org.elasticsearch.common.Strings;
 import org.elasticsearch.common.Table;
+import org.elasticsearch.common.logging.DeprecationLogger;
 import org.elasticsearch.common.unit.TimeValue;
 import org.elasticsearch.index.bulk.stats.BulkStats;
 import org.elasticsearch.index.cache.query.QueryCacheStats;
@@ -60,6 +61,8 @@
 import static org.elasticsearch.rest.RestRequest.Method.GET;
 
 public class RestShardsAction extends AbstractCatAction {
+    private static final DeprecationLogger DEPRECATION_LOGGER = DeprecationLogger.getLogger(RestShardsAction.class);
+    static final String LOCAL_DEPRECATED_MESSAGE = "The parameter [local] is deprecated and will be removed in a future release.";
 
     @Override
     public List<Route> routes() {
@@ -87,6 +90,9 @@ protected void documentation(StringBuilder sb) {
     public RestChannelConsumer doCatRequest(final RestRequest request, final NodeClient client) {
         final String[] indices = Strings.splitStringByCommaToArray(request.param("index"));
         final ClusterStateRequest clusterStateRequest = new ClusterStateRequest();
+        if (request.hasParam("local")) {
+            DEPRECATION_LOGGER.deprecate("local", LOCAL_DEPRECATED_MESSAGE);
+        }
         clusterStateRequest.local(request.paramAsBoolean("local", clusterStateRequest.local()));
         clusterStateRequest.masterNodeTimeout(request.paramAsTime("master_timeout", clusterStateRequest.masterNodeTimeout()));
         clusterStateRequest.clear().nodes(true).routingTable(true).indices(indices);

server/src/test/java/org/elasticsearch/rest/action/cat/RestShardsActionTests.java

@@ -25,6 +25,7 @@
 import org.elasticsearch.action.admin.indices.stats.IndexStats;
 import org.elasticsearch.action.admin.indices.stats.IndicesStatsResponse;
 import org.elasticsearch.action.admin.indices.stats.ShardStats;
+import org.elasticsearch.client.node.NodeClient;
 import org.elasticsearch.cluster.ClusterState;
 import org.elasticsearch.cluster.node.DiscoveryNode;
 import org.elasticsearch.cluster.node.DiscoveryNodes;
@@ -33,9 +34,12 @@
 import org.elasticsearch.cluster.routing.ShardRoutingState;
 import org.elasticsearch.cluster.routing.TestShardRouting;
 import org.elasticsearch.common.Table;
+import org.elasticsearch.common.settings.Settings;
 import org.elasticsearch.index.shard.ShardPath;
 import org.elasticsearch.test.ESTestCase;
 import org.elasticsearch.test.rest.FakeRestRequest;
+import org.elasticsearch.threadpool.TestThreadPool;
+import org.junit.Before;
 
 import java.nio.file.Path;
 import java.util.ArrayList;
@@ -50,6 +54,13 @@
 
 public class RestShardsActionTests extends ESTestCase {
 
+    private RestShardsAction action;
+
+    @Before
+    public void setUpAction() {
+        action = new RestShardsAction();
+    }
+
     public void testBuildTable() {
         final int numShards = randomIntBetween(1, 5);
         DiscoveryNode localNode = new DiscoveryNode("local", buildNewFakeTransportAddress(), Version.CURRENT);
@@ -118,4 +129,16 @@ public void testBuildTable() {
             assertThat(row.get(70).value, equalTo(shardStats.getStatePath()));
         }
     }
+
+    public void testCatNodesWithLocalDeprecationWarning() {
+        TestThreadPool threadPool = new TestThreadPool(RestNodesActionTests.class.getName());
+        NodeClient client = new NodeClient(Settings.EMPTY, threadPool);
+        FakeRestRequest request = new FakeRestRequest();
+        request.params().put("local", randomFrom("", "true", "false"));
+
+        action.doCatRequest(request, client);
+        assertWarnings(RestShardsAction.LOCAL_DEPRECATED_MESSAGE);
+
+        terminate(threadPool);
+    }
 }