HLREST: Add Clear Roles Cache API (#34187)

Adds support for the Clear Roles Cache API to the High Level Rest
Client. As part of this a helper class, NodesResponseHeader, has been
added that enables parsing the nodes header from responses that are
node requests.

Relates to #29827

Author: bleskes

client/rest-high-level/src/main/java/org/elasticsearch/client/NodesResponseHeader.java

@@ -0,0 +1,136 @@
+/*
+ * Licensed to Elasticsearch under one or more contributor
+ * license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright
+ * ownership. Elasticsearch licenses this file to you under
+ * the Apache License, Version 2.0 (the "License"); you may
+ * not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.elasticsearch.client;
+
+import org.elasticsearch.ElasticsearchException;
+import org.elasticsearch.action.support.nodes.BaseNodesResponse;
+import org.elasticsearch.common.Nullable;
+import org.elasticsearch.common.ParseField;
+import org.elasticsearch.common.xcontent.ConstructingObjectParser;
+import org.elasticsearch.common.xcontent.ToXContent;
+import org.elasticsearch.common.xcontent.XContentBuilder;
+import org.elasticsearch.common.xcontent.XContentParser;
+import org.elasticsearch.rest.action.RestActions;
+
+import java.io.IOException;
+import java.util.Collections;
+import java.util.List;
+import java.util.Objects;
+
+/**
+ * A utility class to parse the Nodes Header returned by
+ * {@link RestActions#buildNodesHeader(XContentBuilder, ToXContent.Params, BaseNodesResponse)}.
+ */
+public final class NodesResponseHeader {
+
+    public static final ParseField TOTAL = new ParseField("total");
+    public static final ParseField SUCCESSFUL = new ParseField("successful");
+    public static final ParseField FAILED = new ParseField("failed");
+    public static final ParseField FAILURES = new ParseField("failures");
+
+    @SuppressWarnings("unchecked")
+    public static final ConstructingObjectParser<NodesResponseHeader, Void> PARSER =
+        new ConstructingObjectParser<>("nodes_response_header", true,
+            (a) -> {
+                int i = 0;
+                int total = (Integer) a[i++];
+                int successful = (Integer) a[i++];
+                int failed = (Integer) a[i++];
+                List<ElasticsearchException> failures = (List<ElasticsearchException>) a[i++];
+                return new NodesResponseHeader(total, successful, failed, failures);
+            });
+
+    static {
+        PARSER.declareInt(ConstructingObjectParser.constructorArg(), TOTAL);
+        PARSER.declareInt(ConstructingObjectParser.constructorArg(), SUCCESSFUL);
+        PARSER.declareInt(ConstructingObjectParser.constructorArg(), FAILED);
+        PARSER.declareObjectArray(ConstructingObjectParser.optionalConstructorArg(),
+            (p, c) -> ElasticsearchException.fromXContent(p), FAILURES);
+    }
+
+    private final int total;
+    private final int successful;
+    private final int failed;
+    private final List<ElasticsearchException> failures;
+
+    public NodesResponseHeader(int total, int successful, int failed, @Nullable List<ElasticsearchException> failures) {
+        this.total = total;
+        this.successful = successful;
+        this.failed = failed;
+        this.failures = failures == null ? Collections.emptyList() : failures;
+    }
+
+    public static NodesResponseHeader fromXContent(XContentParser parser, Void context) throws IOException {
+        return PARSER.parse(parser, context);
+    }
+
+    /** the total number of nodes that the operation was carried on */
+    public int getTotal() {
+        return total;
+    }
+
+    /** the number of nodes that the operation has failed on */
+    public int getFailed() {
+        return failed;
+    }
+
+    /** the number of nodes that the operation was successful on */
+    public int getSuccessful() {
+        return successful;
+    }
+
+    /**
+     * Get the failed node exceptions.
+     *
+     * @return Never {@code null}. Can be empty.
+     */
+    public List<ElasticsearchException> getFailures() {
+        return failures;
+    }
+
+    /**
+     * Determine if there are any node failures in {@link #failures}.
+     *
+     * @return {@code true} if {@link #failures} contains at least 1 exception.
+     */
+    public boolean hasFailures() {
+        return failures.isEmpty() == false;
+    }
+
+    @Override
+    public boolean equals(Object o) {
+        if (this == o) {
+            return true;
+        }
+        if (o == null || getClass() != o.getClass()) {
+            return false;
+        }
+        NodesResponseHeader that = (NodesResponseHeader) o;
+        return total == that.total &&
+            successful == that.successful &&
+            failed == that.failed &&
+            Objects.equals(failures, that.failures);
+    }
+
+    @Override
+    public int hashCode() {
+        return Objects.hash(total, successful, failed, failures);
+    }
+
+}

client/rest-high-level/src/main/java/org/elasticsearch/client/SecurityClient.java

@@ -20,17 +20,19 @@
 package org.elasticsearch.client;
 
 import org.elasticsearch.action.ActionListener;
+import org.elasticsearch.client.security.ClearRolesCacheRequest;
+import org.elasticsearch.client.security.ClearRolesCacheResponse;
 import org.elasticsearch.client.security.DeleteRoleRequest;
 import org.elasticsearch.client.security.DeleteRoleResponse;
 import org.elasticsearch.client.security.PutRoleMappingRequest;
 import org.elasticsearch.client.security.PutRoleMappingResponse;
 import org.elasticsearch.client.security.DisableUserRequest;
+import org.elasticsearch.client.security.EmptyResponse;
 import org.elasticsearch.client.security.EnableUserRequest;
 import org.elasticsearch.client.security.GetSslCertificatesRequest;
 import org.elasticsearch.client.security.GetSslCertificatesResponse;
 import org.elasticsearch.client.security.PutUserRequest;
 import org.elasticsearch.client.security.PutUserResponse;
-import org.elasticsearch.client.security.EmptyResponse;
 import org.elasticsearch.client.security.ChangePasswordRequest;
 import org.elasticsearch.client.security.DeleteRoleMappingRequest;
 import org.elasticsearch.client.security.DeleteRoleMappingResponse;
@@ -170,6 +172,36 @@ public void disableUserAsync(DisableUserRequest request, RequestOptions options,
             EmptyResponse::fromXContent, listener, emptySet());
     }
 
+    /**
+     * Clears the native roles cache for a set of roles.
+     * See <a href="https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-clear-role-cache.html">
+     * the docs</a> for more.
+     *
+     * @param request the request with the roles for which the cache should be cleared.
+     * @param options the request options (e.g. headers), use {@link RequestOptions#DEFAULT} if nothing needs to be customized
+     * @return the response from the enable user call
+     * @throws IOException in case there is a problem sending the request or parsing back the response
+     */
+    public ClearRolesCacheResponse clearRolesCache(ClearRolesCacheRequest request, RequestOptions options) throws IOException {
+        return restHighLevelClient.performRequestAndParseEntity(request, SecurityRequestConverters::clearRolesCache, options,
+            ClearRolesCacheResponse::fromXContent, emptySet());
+    }
+
+    /**
+     * Clears the native roles cache for a set of roles asynchronously.
+     * See <a href="https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-clear-role-cache.html">
+     * the docs</a> for more.
+     *
+     * @param request  the request with the roles for which the cache should be cleared.
+     * @param options  the request options (e.g. headers), use {@link RequestOptions#DEFAULT} if nothing needs to be customized
+     * @param listener the listener to be notified upon request completion
+     */
+    public void clearRolesCacheAsync(ClearRolesCacheRequest request, RequestOptions options,
+                                     ActionListener<ClearRolesCacheResponse> listener) {
+        restHighLevelClient.performRequestAsyncAndParseEntity(request, SecurityRequestConverters::clearRolesCache, options,
+            ClearRolesCacheResponse::fromXContent, listener, emptySet());
+    }
+
     /**
      * Synchronously retrieve the X.509 certificates that are used to encrypt communications in an Elasticsearch cluster.
      * See <a href="https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-ssl.html">

client/rest-high-level/src/main/java/org/elasticsearch/client/SecurityRequestConverters.java

@@ -22,6 +22,7 @@
 import org.apache.http.client.methods.HttpDelete;
 import org.apache.http.client.methods.HttpPost;
 import org.apache.http.client.methods.HttpPut;
+import org.elasticsearch.client.security.ClearRolesCacheRequest;
 import org.elasticsearch.client.security.DeleteRoleMappingRequest;
 import org.elasticsearch.client.security.DeleteRoleRequest;
 import org.elasticsearch.client.security.PutRoleMappingRequest;
@@ -97,6 +98,15 @@ private static Request setUserEnabled(SetUserEnabledRequest setUserEnabledReques
         return request;
     }
 
+    static Request clearRolesCache(ClearRolesCacheRequest disableCacheRequest) {
+        String endpoint = new RequestConverters.EndpointBuilder()
+            .addPathPartAsIs("_xpack/security/role")
+            .addCommaSeparatedPathParts(disableCacheRequest.names())
+            .addPathPart("_clear_cache")
+            .build();
+        return new Request(HttpPost.METHOD_NAME, endpoint);
+    }
+
     static Request deleteRoleMapping(DeleteRoleMappingRequest deleteRoleMappingRequest) {
         final String endpoint = new RequestConverters.EndpointBuilder()
             .addPathPartAsIs("_xpack/security/role_mapping")

client/rest-high-level/src/main/java/org/elasticsearch/client/security/ClearRolesCacheRequest.java

@@ -0,0 +1,65 @@
+/*
+ * Licensed to Elasticsearch under one or more contributor
+ * license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright
+ * ownership. Elasticsearch licenses this file to you under
+ * the Apache License, Version 2.0 (the "License"); you may
+ * not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+package org.elasticsearch.client.security;
+
+import org.elasticsearch.client.Validatable;
+
+import java.util.Arrays;
+
+/**
+ * The request used to clear the cache for native roles stored in an index.
+ */
+public final class ClearRolesCacheRequest implements Validatable {
+
+    private final String[] names;
+
+    /**
+     * Sets the roles for which caches will be evicted. When not set all the roles will be evicted from the cache.
+     *
+     * @param names    The role names
+     */
+    public ClearRolesCacheRequest(String... names) {
+        this.names = names;
+    }
+
+    /**
+     * @return an array of role names that will have the cache evicted or <code>null</code> if all
+     */
+    public String[] names() {
+        return names;
+    }
+
+    @Override
+    public boolean equals(Object o) {
+        if (this == o) {
+            return true;
+        }
+        if (o == null || getClass() != o.getClass()) {
+            return false;
+        }
+        ClearRolesCacheRequest that = (ClearRolesCacheRequest) o;
+        return Arrays.equals(names, that.names);
+    }
+
+    @Override
+    public int hashCode() {
+        return Arrays.hashCode(names);
+    }
+}

client/rest-high-level/src/main/java/org/elasticsearch/client/security/ClearRolesCacheResponse.java

@@ -0,0 +1,109 @@
+/*
+ * Licensed to Elasticsearch under one or more contributor
+ * license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright
+ * ownership. Elasticsearch licenses this file to you under
+ * the Apache License, Version 2.0 (the "License"); you may
+ * not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+package org.elasticsearch.client.security;
+
+import org.elasticsearch.client.NodesResponseHeader;
+import org.elasticsearch.common.ParseField;
+import org.elasticsearch.common.xcontent.ConstructingObjectParser;
+import org.elasticsearch.common.xcontent.XContentParser;
+
+import java.io.IOException;
+import java.util.List;
+import java.util.Objects;
+
+/**
+ * The response object that will be returned when clearing the cache of native roles
+ */
+public final class ClearRolesCacheResponse {
+
+    @SuppressWarnings("unchecked")
+    private static final ConstructingObjectParser<ClearRolesCacheResponse, Void> PARSER =
+        new ConstructingObjectParser<>("clear_roles_cache_response", false,
+            args -> new ClearRolesCacheResponse((List<Node>)args[0], (NodesResponseHeader) args[1], (String) args[2]));
+
+    static {
+        PARSER.declareNamedObjects(ConstructingObjectParser.constructorArg(), (p, c, n) -> Node.PARSER.apply(p, n),
+            new ParseField("nodes"));
+        PARSER.declareObject(ConstructingObjectParser.constructorArg(), NodesResponseHeader::fromXContent, new ParseField("_nodes"));
+        PARSER.declareString(ConstructingObjectParser.constructorArg(), new ParseField("cluster_name"));
+    }
+
+    private final List<Node> nodes;
+    private final NodesResponseHeader header;
+    private final String clusterName;
+
+    public ClearRolesCacheResponse(List<Node> nodes, NodesResponseHeader header, String clusterName) {
+        this.nodes = nodes;
+        this.header = header;
+        this.clusterName = Objects.requireNonNull(clusterName, "cluster name must be provided");
+    }
+
+    /** returns a list of nodes in which the cache was cleared */
+    public List<Node> getNodes() {
+        return nodes;
+    }
+
+    /**
+     * Get the cluster name associated with all of the nodes.
+     *
+     * @return Never {@code null}.
+     */
+    public String getClusterName() {
+        return clusterName;
+    }
+
+    /**
+     * Gets information about the number of total, successful and failed nodes the request was run on.
+     * Also includes exceptions if relevant.
+     */
+    public NodesResponseHeader getHeader() {
+        return header;
+    }
+
+    public static class Node {
+
+        private static final ConstructingObjectParser<Node, String> PARSER =
+            new ConstructingObjectParser<>("clear_roles_cache_response_node", false, (args, id) -> new Node(id, (String) args[0]));
+
+        static {
+            PARSER.declareString(ConstructingObjectParser.constructorArg(), new ParseField("name"));
+        }
+
+        private final String id;
+        private final String name;
+
+        public Node(String id, String name) {
+            this.id = id;
+            this.name = name;
+        }
+
+        public String getId() {
+            return id;
+        }
+
+        public String getName() {
+            return name;
+        }
+    }
+
+    public static ClearRolesCacheResponse fromXContent(XContentParser parser) throws IOException {
+        return PARSER.parse(parser, null);
+    }
+}