Support recording index resolution results on IndicesRequest (#134783)

This PR introduces `ResolvedIndexExpression` and
`ResolvedIndexExpressions` classes to capture context about index
resolution (local results, exceptions, and unresolved remote
expressions).

`IndicesRequest.Replaceable` now provides optional methods to set and
retrieve resolved index expressions, enabling requests to carry richer
resolution metadata alongside the existing `indices(...)` API.

Follow up work will plug this class into `IndicesAndAliasesResolver`. 

This change is motivated by the requirements around error handling for
cross-project search where error handling is performed post local index
resolution in some cases.

Closes: ES-12688

Author: n1v0lg

server/src/main/java/org/elasticsearch/action/IndicesRequest.java

@@ -10,6 +10,7 @@
 package org.elasticsearch.action;
 
 import org.elasticsearch.action.support.IndicesOptions;
+import org.elasticsearch.core.Nullable;
 import org.elasticsearch.index.shard.ShardId;
 
 import java.util.Collection;
@@ -48,9 +49,25 @@ interface Replaceable extends IndicesRequest {
          */
         IndicesRequest indices(String... indices);
 
+        /**
+         * Record the results of index resolution. See {@link ResolvedIndexExpressions} for details.
+         * Note: this method does not replace {@link #indices(String...)}. {@link #indices(String...)} must still be called to update
+         * the actual list of indices the request relates to.
+         */
+        default void setResolvedIndexExpressions(ResolvedIndexExpressions expressions) {}
+
+        /**
+         * Returns the results of index resolution, if recorded via
+         * {@link #setResolvedIndexExpressions(ResolvedIndexExpressions)}. Null if not recorded.
+         */
+        @Nullable
+        default ResolvedIndexExpressions getResolvedIndexExpressions() {
+            return null;
+        }
+
         /**
          * Determines whether the request can contain indices on a remote cluster.
-         *
+         * <p>
          * NOTE in theory this method can belong to the {@link IndicesRequest} interface because whether a request
          * allowing remote indices has no inherent relationship to whether it is {@link Replaceable} or not.
          * However, we don't have an existing request that is non-replaceable but allows remote indices.

server/src/main/java/org/elasticsearch/action/ResolvedIndexExpression.java

@@ -0,0 +1,68 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the "Elastic License
+ * 2.0", the "GNU Affero General Public License v3.0 only", and the "Server Side
+ * Public License v 1"; you may not use this file except in compliance with, at
+ * your election, the "Elastic License 2.0", the "GNU Affero General Public
+ * License v3.0 only", or the "Server Side Public License, v 1".
+ */
+
+package org.elasticsearch.action;
+
+import org.elasticsearch.ElasticsearchException;
+import org.elasticsearch.core.Nullable;
+
+import java.util.List;
+
+/**
+ * This class allows capturing context about index expression replacements performed on an {@link IndicesRequest.Replaceable} during
+ * index resolution, in particular the results of local resolution, and the remote (unresolved) expressions if any.
+ * <p>
+ * The replacements are separated into local and remote expressions.
+ * For local expressions, the class allows recording local index resolution results along with failure info.
+ * For remote expressions, only the expressions are recorded.
+ *
+ * <p>An example structure is:</p>
+ *
+ * <pre>{@code
+ * {
+ *   "original": "my-index-*",
+ *   "localExpressions": {
+ *     "expressions": ["my-index-000001", "my-index-000002"],
+ *     "localIndexResolutionResult": "SUCCESS"
+ *   },
+ *   "remoteExpressions": ["remote1:my-index-*", "remote2:my-index-*"]
+ * }
+ * }</pre>
+ *
+ * @param original the original index expression, as provided by the user
+ * @param localExpressions the local expressions that replace the original along with their resolution result
+ *                         and failure info
+ * @param remoteExpressions the remote expressions that replace the original
+ */
+public record ResolvedIndexExpression(String original, LocalExpressions localExpressions, List<String> remoteExpressions) {
+    /**
+     * Indicates if a local index resolution attempt was successful or failed.
+     * Failures can be due to missing concrete resources or unauthorized concrete resources.
+     * A wildcard expression resolving to nothing is still considered a successful resolution.
+     */
+    enum LocalIndexResolutionResult {
+        SUCCESS,
+        CONCRETE_RESOURCE_MISSING,
+        CONCRETE_RESOURCE_UNAUTHORIZED,
+    }
+
+    /**
+     * Represents local (non-remote) resolution results, including expanded indices, and the resolution result.
+     */
+    public record LocalExpressions(
+        List<String> expressions,
+        LocalIndexResolutionResult localIndexResolutionResult,
+        @Nullable ElasticsearchException exception
+    ) {
+        public LocalExpressions {
+            assert localIndexResolutionResult != LocalIndexResolutionResult.SUCCESS || exception == null
+                : "If the local resolution result is SUCCESS, exception must be null";
+        }
+    }
+}

server/src/main/java/org/elasticsearch/action/ResolvedIndexExpressions.java

@@ -0,0 +1,40 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the "Elastic License
+ * 2.0", the "GNU Affero General Public License v3.0 only", and the "Server Side
+ * Public License v 1"; you may not use this file except in compliance with, at
+ * your election, the "Elastic License 2.0", the "GNU Affero General Public
+ * License v3.0 only", or the "Server Side Public License, v 1".
+ */
+
+package org.elasticsearch.action;
+
+import java.util.Map;
+
+/**
+ * A collection of {@link ResolvedIndexExpression}, keyed by the original expression.
+ *
+ * <p>An example structure is:</p>
+ *
+ * <pre>{@code
+ * {
+ *   "my-index-*": {
+ *      "original": "my-index-*",
+ *      "localExpressions": {
+ *          "expressions": ["my-index-000001", "my-index-000002"],
+ *          "localIndexResolutionResult": "SUCCESS"
+ *      },
+ *      "remoteExpressions": ["remote1:my-index-*", "remote2:my-index-*"]
+ *   },
+ *   "my-index-000001": {
+ *      "original": "my-index-000001",
+ *      "localExpressions": {
+ *          "expressions": ["my-index-000001"],
+ *          "localIndexResolutionResult": "SUCCESS"
+ *      },
+ *      "remoteExpressions": ["remote1:my-index-000001", "remote2:my-index-000001"]
+ *   }
+ * }
+ * }</pre>
+ */
+public record ResolvedIndexExpressions(Map<String, ResolvedIndexExpression> expressions) {}