Add granular error list to alias action response

docs/changelog/106514.yaml

@@ -0,0 +1,6 @@
+pr: 106514
+summary: Add granular error list to alias action response
+area: Indices APIs
+type: feature
+issues:
+ - 94478

docs/reference/alias.asciidoc

@@ -121,6 +121,64 @@ 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.
+
+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 set `must_exist` to `true`, which will cause the entire action
+list to fail if a single action fails.
+
+
 [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`::
@@ -168,3 +174,38 @@ stream aliases don't support this parameter.
 Only the `add` action supports this parameter.
 =====
 ====
+
+
+
+[role="child_attributes"]
+[[indices-aliases-api-response-body]]
+==== {api-response-body-title}
+
+`acknowledged`::
+(Boolean)
+If `true`, the request received a response from the master node within the
+`timeout` period.
+
+`errors`::
+(Boolean)
+If `true`, at least one of the requested actions failed.
+
+`action_results`::
+(array of objects) Results for each requested action.
++
+.Properties of `action_results` objects
+[%collapsible%open]
+====
+
+`action`::
+(string)
+The type of the associated action, the values will be one of `add`, `remove`, or `remove_index`.
+
+`success`::
+(boolean)
+If true, the requested action was successfully applied at least once.
+
+`error`::
+(Optional, string)
+Only present if `success` is `false`. Consists of a message describing why the action failed
+====

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: " - 8.13.99"
+      reason: "alias action results do not work until 8.14"
+      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: " - 8.13.99"
+      reason: "alias action results do not work until 8.14"
+      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,98 @@
             - remove_index:
                 index: test_index
                 must_exist: true
+---
+"Partial success with must_exist == false":
+  - skip:
+      version: " - 8.13.99"
+      reason: "alias action results do not work until 8.14"
+  - 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)":
+  - skip:
+      version: " - 8.13.99"
+      reason: "alias action results do not work until 8.14"
+  - 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":
+  - skip:
+      version: " - 8.13.99"
+      reason: "alias action results do not work until 8.14"
+  - 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":
+  - skip:
+      version: " - 8.13.99"
+      reason: "alias action results do not work until 8.14"
+  - 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/TransportVersions.java

@@ -151,6 +151,7 @@ static TransportVersion def(int id) {
     public static final TransportVersion AUTO_SHARDING_ROLLOVER_CONDITION = def(8_611_00_0);
     public static final TransportVersion KNN_QUERY_VECTOR_BUILDER = def(8_612_00_0);
     public static final TransportVersion USE_DATA_STREAM_GLOBAL_RETENTION = def(8_613_00_0);
+    public static final TransportVersion ALIAS_ACTION_RESULTS = def(8_614_00_0);
 
     /*
      * STOP! READ THIS FIRST! No, really,

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) {