Add granular error list to alias action response

docs/reference/alias.asciidoc

@@ -121,6 +121,66 @@ POST _aliases
 // TEST[s/^/PUT _data_stream\/logs-nginx.access-prod\nPUT _data_stream\/logs-my_app-default\n/]
 // end::alias-multiple-actions-example[]
 
+[discrete]
+[[Multiple action results]]
+=== Multiple action results
+
+When using multiple actions, if some succeed and some fail, a list of per-action results will be returned.
+
+// tag::alias-multiple-actions-result-example[]
+Consider a similar action list to the previous example, but now with an alias `log-non-existing`, which does not yet exist.
+In this case, the `remove` action will fail, but the `add` action will succeed.
+The response will contain the list `action_results`, with a result for every requested action.
+
+[source,console]
+----
+POST _aliases
+{
+  "actions": [
+    {
+      "remove": {
+        "index": "index1",
+        "alias": "logs-non-existing"
+      }
+    },
+    {
+      "add": {
+        "index": "index2",
+        "alias": "logs-non-existing"
+      }
+    }
+  ]
+}
+----
+// TEST[s/^/PUT \/index1\nPUT \/index2\n/]
+
+The API returns the following result:
+
+[source,console-result]
+--------------------------------------------------
+{
+  "acknowledged": true,
+  "errors": true,
+  "action_results": [
+    {
+      "action": "remove",
+      "success": false,
+      "error": "aliases_not_found_exception"
+    },
+    {
+      "action": "add",
+      "success": true
+    }
+  ]
+}
+--------------------------------------------------
+
+Allowing the action list to succeed partially may not provide the desired result.
+It may be more appropriate to use set `must_exist` to `true`, which will cause the entire action
+list to fail if a single action fails.
+
+// end::alias-multiple-actions-example[]
+
 [discrete]
 [[add-alias-at-creation]]
 === Add an alias at index creation

docs/reference/indices/aliases.asciidoc

@@ -145,10 +145,16 @@ the alias points to one data stream.
 +
 Only the `add` action supports this parameter.
 
+// tag::alias-options[]
 `must_exist`::
 (Optional, Boolean)
-If `true`, the alias must exist to perform the action. Defaults to `false`. Only
-the `remove` action supports this parameter.
+Affects the behavior when attempting to remove an alias which does not exist.
+If `true`, removing an alias which does not exist will cause all actions to fail.
+If `false`, removing an alias which does not exist will only cause that removal to fail.
+Defaults to `false`.
+// end::alias-options[]
++
+Only the `remove` action supports this parameter.
 
 // tag::alias-options[]
 `routing`::

modules/data-streams/src/yamlRestTest/resources/rest-api-spec/test/data_stream/140_data_stream_aliases.yml

@@ -307,3 +307,84 @@
       indices.get_alias:
         name: this-does-not-exist*
   - is_false: ds-first.aliases.my-alias
+---
+"Action Results with multiple matching aliases":
+  - skip:
+      version: " - 7.13.99"
+      reason: "data streams aliases are available from 7.14.0"
+      features: allowed_warnings
+  - do:
+      allowed_warnings:
+        - "index template [my-template] has index patterns [log-*] matching patterns from existing older templates [global] with patterns (global => [*]); this template [my-template] will take precedence during new index creation"
+      indices.put_index_template:
+        name: my-template
+        body:
+          index_patterns: [ log-* ]
+          template:
+            settings:
+              index.number_of_replicas: 0
+          data_stream: { }
+  - do:
+      indices.create_data_stream:
+        name: log-foobar
+  - is_true: acknowledged
+  - do:
+      indices.update_aliases:
+        body:
+          actions:
+            - add:
+                index: log-foobar
+                aliases: test_alias1
+            - remove:
+                index: log-foobar
+                aliases: test_non_existing
+                must_exist: false
+  - is_true: errors
+  - length: { action_results: 2 }
+  - match: { action_results.0.success: true }
+  - match: { action_results.0.action: add }
+  - match: { action_results.1.success: false }
+  - match: { action_results.1.action: remove }
+  - match: { action_results.1.error: aliases_not_found_exception }
+---
+"Single action result per action":
+  - skip:
+      version: " - 7.13.99"
+      reason: "data streams aliases are available from 7.14.0"
+      features: allowed_warnings
+  - do:
+      allowed_warnings:
+        - "index template [my-template] has index patterns [log-*] matching patterns from existing older templates [global] with patterns (global => [*]); this template [my-template] will take precedence during new index creation"
+      indices.put_index_template:
+        name: my-template
+        body:
+          index_patterns: [ log-* ]
+          template:
+            settings:
+              index.number_of_replicas: 0
+          data_stream: { }
+  - do:
+      indices.create_data_stream:
+        name: log-test-1
+  - do:
+      indices.create_data_stream:
+        name: log-test-2
+  - is_true: acknowledged
+  - do:
+      indices.update_aliases:
+        body:
+          actions:
+            - add:
+                index: log-test-*
+                aliases: test_alias1
+            - remove:
+                index: log-test-*
+                aliases: test_non_existing
+                must_exist: false
+  - is_true: errors
+  - length: { action_results: 2 }
+  - match: { action_results.0.success: true }
+  - match: { action_results.0.action: add }
+  - match: { action_results.1.success: false }
+  - match: { action_results.1.action: remove }
+  - match: { action_results.1.error: aliases_not_found_exception }

rest-api-spec/src/yamlRestTest/resources/rest-api-spec/test/indices.update_aliases/40_must_exist.yml

@@ -82,3 +82,86 @@
             - remove_index:
                 index: test_index
                 must_exist: true
+---
+"Partial success with must_exist == false":
+  - do:
+      indices.create:
+        index: test_index
+  - do:
+      indices.update_aliases:
+        body:
+          actions:
+            - add:
+                index: test_index
+                aliases: test_alias1
+            - remove:
+                index: test_index
+                aliases: test_non_existing
+                must_exist: false
+  - is_true: errors
+  - match: { action_results.0.success: true }
+  - match: { action_results.0.action: add }
+  - match: { action_results.1.success: false }
+  - match: { action_results.1.action: remove }
+  - match: { action_results.1.error: aliases_not_found_exception }
+---
+"Partial success with must_exist == null (default)":
+  - do:
+      indices.create:
+        index: test_index
+  - do:
+      indices.update_aliases:
+        body:
+          actions:
+            - add:
+                index: test_index
+                aliases: test_alias1
+            - remove:
+                index: test_index
+                aliases: test_non_existing
+  - is_true: errors
+  - match: { action_results.0.success: true }
+  - match: { action_results.0.action: add }
+  - match: { action_results.1.success: false }
+  - match: { action_results.1.action: remove }
+  - match: { action_results.1.error: aliases_not_found_exception }
+---
+"No action_results field if all actions successful":
+  - do:
+      indices.create:
+        index: test_index
+  - do:
+     indices.update_aliases:
+      body:
+        actions:
+          - add:
+              index: test_index
+              aliases: test_alias1
+  - is_false: errors
+  - match: { action_results: null }
+---
+"Single result per input action":
+  - do:
+      indices.create:
+        index: test_index1
+  - do:
+      indices.create:
+        index: test_index2
+  - do:
+      indices.update_aliases:
+        body:
+          actions:
+            - add:
+                index: test_index*
+                aliases: test_alias1
+            - remove:
+                index: test_index*
+                aliases: test_non_existing
+  - length: { action_results: 2 }
+  - is_true: errors
+  - match: { action_results.0.success: true }
+  - match: { action_results.0.action: add }
+  - match: { action_results.1.success: false }
+  - match: { action_results.1.action: remove }
+  - match: { action_results.1.error: aliases_not_found_exception }
+

server/src/main/java/org/elasticsearch/action/admin/indices/alias/IndicesAliasesClusterStateUpdateRequest.java

@@ -7,6 +7,7 @@
  */
 package org.elasticsearch.action.admin.indices.alias;
 
+import org.elasticsearch.action.admin.indices.alias.IndicesAliasesResponse.AliasActionResult;
 import org.elasticsearch.cluster.ack.ClusterStateUpdateRequest;
 import org.elasticsearch.cluster.metadata.AliasAction;
 
@@ -18,8 +19,11 @@
 public class IndicesAliasesClusterStateUpdateRequest extends ClusterStateUpdateRequest<IndicesAliasesClusterStateUpdateRequest> {
     private final List<AliasAction> actions;
 
-    public IndicesAliasesClusterStateUpdateRequest(List<AliasAction> actions) {
+    private final List<IndicesAliasesResponse.AliasActionResult> actionResults;
+
+    public IndicesAliasesClusterStateUpdateRequest(List<AliasAction> actions, List<AliasActionResult> actionResults) {
         this.actions = actions;
+        this.actionResults = actionResults;
     }
 
     /**
@@ -28,4 +32,8 @@ public IndicesAliasesClusterStateUpdateRequest(List<AliasAction> actions) {
     public List<AliasAction> actions() {
         return actions;
     }
+
+    public List<AliasActionResult> getActionResults() {
+        return actionResults;
+    }
 }

server/src/main/java/org/elasticsearch/action/admin/indices/alias/IndicesAliasesRequest.java

@@ -105,6 +105,10 @@ public byte value() {
                 return value;
             }
 
+            public String getFieldName() {
+                return fieldName;
+            }
+
             public static Type fromValue(byte value) {
                 return switch (value) {
                     case 0 -> ADD;

server/src/main/java/org/elasticsearch/action/admin/indices/alias/IndicesAliasesRequestBuilder.java

@@ -10,7 +10,6 @@
 
 import org.elasticsearch.action.admin.indices.alias.IndicesAliasesRequest.AliasActions;
 import org.elasticsearch.action.support.master.AcknowledgedRequestBuilder;
-import org.elasticsearch.action.support.master.AcknowledgedResponse;
 import org.elasticsearch.client.internal.ElasticsearchClient;
 import org.elasticsearch.index.query.QueryBuilder;
 
@@ -21,7 +20,7 @@
  */
 public class IndicesAliasesRequestBuilder extends AcknowledgedRequestBuilder<
     IndicesAliasesRequest,
-    AcknowledgedResponse,
+    IndicesAliasesResponse,
     IndicesAliasesRequestBuilder> {
 
     public IndicesAliasesRequestBuilder(ElasticsearchClient client) {