Introduce ?wait_for_active_shards=index-setting (#67158)

In 7.x the close indices API defaulted to `?wait_for_active_shards=0`
but from 8.0 it defaults to respecting the index settings instead.  This
commit introduces the `index-setting` value for this parameter on this
API allowing users to opt-in to the future behaviour today, and emits a
deprecation warning indicating that the default no longer needs to be
used and will be unsupported in future.

In 7.x a follow up PR will introduce support for the same
`index-setting` value for this parameter and will emit deprecation
warnings if users try and use the default instead.

Relates #66419

Author: DaveCTurner

docs/reference/migration/migrate_8_0/indices.asciidoc

@@ -102,3 +102,18 @@ Discontinue use of the `index.translog.retention.age` and
 `index.translog.retention.size` index settings. Requests that
 include these settings will return an error.
 ====
+
+.The default for the `?wait_for_active_shards` parameter on the close index API has changed.
+[%collapsible]
+====
+*Details* +
+When closing an index in earlier versions, by default {es} would not wait for
+the shards of the closed index to be properly assigned before returning. From
+version 8.0 onwards the default behaviour is to wait for shards to be assigned
+according to the <<index-wait-for-active-shards,index setting
+`index.write.wait_for_active_shards`>>.
+
+*Impact* +
+Accept the new behaviour, or specify `?wait_for_active_shards=0` to preserve
+the old behaviour if needed.
+====

rest-api-spec/src/main/resources/rest-api-spec/test/indices.open/10_basic.yml

@@ -81,10 +81,6 @@
   - match: { shards_acknowledged: true }
 ---
 "Close index response with result per index":
-  - skip:
-      version: " - 7.2.99"
-      reason: "close index response reports result per index starting version 7.3.0"
-
   - do:
       indices.create:
         index: index_1
@@ -115,3 +111,26 @@
   - match: { indices.index_1.closed: true }
   - match: { indices.index_2.closed: true }
   - match: { indices.index_3.closed: true }
+
+---
+"?wait_for_active_shards=index-setting is deprecated":
+  - skip:
+      version: " - 7.99.99"
+      reason: "required deprecation warning is only emitted in 8.0 and later"
+      features: ["warnings", "node_selector"]
+
+  - do:
+      indices.create:
+        index: index_1
+        body:
+          settings:
+            number_of_replicas: 0
+
+  - do:
+      indices.close:
+        index: "index_*"
+        wait_for_active_shards: index-setting
+      node_selector:
+        version: "8.0.0 - "
+      warnings:
+        - "?wait_for_active_shards=index-setting is now the default behaviour; the 'index-setting' value for this parameter should no longer be used since it will become unsupported in version 9"

server/src/main/java/org/elasticsearch/rest/action/admin/indices/RestCloseIndexAction.java

@@ -19,11 +19,13 @@
 
 package org.elasticsearch.rest.action.admin.indices;
 
+import org.elasticsearch.Version;
 import org.elasticsearch.action.admin.indices.close.CloseIndexRequest;
 import org.elasticsearch.action.support.ActiveShardCount;
 import org.elasticsearch.action.support.IndicesOptions;
 import org.elasticsearch.client.node.NodeClient;
 import org.elasticsearch.common.Strings;
+import org.elasticsearch.common.logging.DeprecationLogger;
 import org.elasticsearch.rest.BaseRestHandler;
 import org.elasticsearch.rest.RestRequest;
 import org.elasticsearch.rest.action.RestToXContentListener;
@@ -35,6 +37,8 @@
 
 public class RestCloseIndexAction extends BaseRestHandler {
 
+    private static final DeprecationLogger deprecationLogger = DeprecationLogger.getLogger(RestCloseIndexAction.class);
+
     @Override
     public List<Route> routes() {
         return List.of(
@@ -54,7 +58,17 @@ public RestChannelConsumer prepareRequest(final RestRequest request, final NodeC
         closeIndexRequest.timeout(request.paramAsTime("timeout", closeIndexRequest.timeout()));
         closeIndexRequest.indicesOptions(IndicesOptions.fromRequest(request, closeIndexRequest.indicesOptions()));
         String waitForActiveShards = request.param("wait_for_active_shards");
-        if (waitForActiveShards != null) {
+        if ("index-setting".equalsIgnoreCase(waitForActiveShards)) {
+            deprecationLogger.deprecate("close-index-wait_for_active_shards-index-setting",
+                    "?wait_for_active_shards=index-setting is now the default behaviour; the 'index-setting' value for this parameter " +
+                            "should no longer be used since it will become unsupported in version " + (Version.V_7_0_0.major + 2));
+            // TODO in v9:
+            //  - throw an IllegalArgumentException here
+            //  - record the removal of support for this value as a breaking change.
+            //  - mention Version.V_8_0_0 in the code to ensure that we revisit this in v10
+            // TODO in v10:
+            //  - remove the IllegalArgumentException here
+        } else if (waitForActiveShards != null) {
             closeIndexRequest.waitForActiveShards(ActiveShardCount.parseString(waitForActiveShards));
         }
         return channel -> client.admin().indices().close(closeIndexRequest, new RestToXContentListener<>(channel));