LLClient: Support host selection

Allows users of the Low Level REST client to specify which hosts a
request should be run on. They implement the  `NodeSelector` interface
or reuse a built in selector like `NOT_MASTER_ONLY` to chose which nodes
are valid. Using it looks like:
```
Request request = new Request("POST", "/foo/_search");
request.setNodeSelector(NodeSelector.NOT_MASTER_ONLY);
...
```

This introduces a new `Node` object which contains a `HttpHost` and the
metadata about the host. At this point that metadata is just `version`
and `roles` but I plan to add node attributes in a followup. The
canonical way to **get** this metadata is to use the `Sniffer` to pull
the information from the Elasticsearch cluster.

I've marked this as "breaking-java" because it breaks custom
implementations of `HostsSniffer` by renaming the interface to
`NodesSniffer` and by changing it from returning a `List<HttpHost>` to a
`List<Node>`. It *shouldn't* break anyone else though.

Because we expect to find it useful, this also implements `host_selector`
support to `do` statements in the yaml tests. Using it looks a little
like:

```
---
"example test":
  - skip:
      features: host_selector
  - do:
      host_selector:
        version: " - 7.0.0" # same syntax as skip
      apiname:
        something: true
```

The `do` section parses the `version` string into a host selector that
uses the same version comparison logic as the `skip` section. When the
`do` section is executed it passed the off to the `RestClient`, using
the `ElasticsearchHostsSniffer` to sniff the required metadata.

The idea is to use this in mixed version tests to target a specific
version of Elasticsearch so we can be sure about the deprecation
logging though we don't currently have any examples that need it. We do,
however, have at least one open pull request that requires something
like this to properly test it.

Closes elastic#21888 (kind of, it isn't in the high level client, but we'll do
that in a followup)

Author: nik9000

client/rest/src/main/java/org/elasticsearch/client/DeadHostState.java

@@ -29,47 +29,35 @@
 final class DeadHostState implements Comparable<DeadHostState> {
 
     private static final long MIN_CONNECTION_TIMEOUT_NANOS = TimeUnit.MINUTES.toNanos(1);
-    private static final long MAX_CONNECTION_TIMEOUT_NANOS = TimeUnit.MINUTES.toNanos(30);
+    static final long MAX_CONNECTION_TIMEOUT_NANOS = TimeUnit.MINUTES.toNanos(30);
 
     private final int failedAttempts;
     private final long deadUntilNanos;
-    private final TimeSupplier timeSupplier;
 
     /**
      * Build the initial dead state of a host. Useful when a working host stops functioning
      * and needs to be marked dead after its first failure. In such case the host will be retried after a minute or so.
      *
-     * @param timeSupplier a way to supply the current time and allow for unit testing
+     * @param now the current time in nanoseconds. Prefer a source designed to measure elapsed time like {@link System#nanoTime()}.
      */
-    DeadHostState(TimeSupplier timeSupplier) {
+    DeadHostState(long now) {
         this.failedAttempts = 1;
-        this.deadUntilNanos = timeSupplier.nanoTime() + MIN_CONNECTION_TIMEOUT_NANOS;
-        this.timeSupplier = timeSupplier;
+        this.deadUntilNanos = now + MIN_CONNECTION_TIMEOUT_NANOS;
     }
 
     /**
      * Build the dead state of a host given its previous dead state. Useful when a host has been failing before, hence
      * it already failed for one or more consecutive times. The more failed attempts we register the longer we wait
      * to retry that same host again. Minimum is 1 minute (for a node the only failed once created
-     * through {@link #DeadHostState(TimeSupplier)}), maximum is 30 minutes (for a node that failed more than 10 consecutive times)
+     * through {@link #DeadHostState(long)}), maximum is 30 minutes (for a node that failed more than 10 consecutive times)
      *
-     * @param previousDeadHostState the previous state of the host which allows us to increase the wait till the next retry attempt
+     * @param now the current time in nanoseconds. Prefer a source designed to measure elapsed time like {@link System#nanoTime()}.
      */
-    DeadHostState(DeadHostState previousDeadHostState, TimeSupplier timeSupplier) {
+    DeadHostState(DeadHostState previousDeadHostState, long now) {
         long timeoutNanos = (long)Math.min(MIN_CONNECTION_TIMEOUT_NANOS * 2 * Math.pow(2, previousDeadHostState.failedAttempts * 0.5 - 1),
                 MAX_CONNECTION_TIMEOUT_NANOS);
-        this.deadUntilNanos = timeSupplier.nanoTime() + timeoutNanos;
+        this.deadUntilNanos = now + timeoutNanos;
         this.failedAttempts = previousDeadHostState.failedAttempts + 1;
-        this.timeSupplier = timeSupplier;
-    }
-
-    /**
-     * Indicates whether it's time to retry to failed host or not.
-     *
-     * @return true if the host should be retried, false otherwise
-     */
-    boolean shallBeRetried() {
-        return timeSupplier.nanoTime() - deadUntilNanos > 0;
     }
 
     /**
@@ -96,19 +84,4 @@ public String toString() {
                 ", deadUntilNanos=" + deadUntilNanos +
                 '}';
     }
-
-    /**
-     * Time supplier that makes timing aspects pluggable to ease testing
-     */
-    interface TimeSupplier {
-
-        TimeSupplier DEFAULT = new TimeSupplier() {
-            @Override
-            public long nanoTime() {
-                return System.nanoTime();
-            }
-        };
-
-        long nanoTime();
-    }
 }

client/rest/src/main/java/org/elasticsearch/client/Node.java

@@ -0,0 +1,235 @@
+/*
+ * 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 static java.util.Collections.unmodifiableSet;
+
+import java.util.HashSet;
+import java.util.Objects;
+import java.util.Set;
+
+import org.apache.http.HttpHost;
+
+/**
+ * Metadata about an {@link HttpHost} running Elasticsearch.
+ */
+public class Node {
+    /**
+     * Address that this host claims is its primary contact point.
+     */
+    private final HttpHost host;
+    /**
+     * Addresses on which the host is listening. These are useful to have
+     * around because they allow you to find a host based on any address it
+     * is listening on.
+     */
+    private final Set<HttpHost> boundHosts;
+    /**
+     * Name of the node as configured by the {@code node.name} attribute.
+     */
+    private final String name;
+    /**
+     * Version of Elasticsearch that the node is running or {@code null}
+     * if we don't know the version.
+     */
+    private final String version;
+    /**
+     * Roles that the Elasticsearch process on the host has or {@code null}
+     * if we don't know what roles the node has.
+     */
+    private final Roles roles;
+
+    /**
+     * Create a {@linkplain Node} with metadata. All parameters except
+     * {@code host} are nullable and implementations of {@link NodeSelector}
+     * need to decide what to do in their absence.
+     */
+    public Node(HttpHost host, Set<HttpHost> boundHosts, String name, String version, Roles roles) {
+        if (host == null) {
+            throw new IllegalArgumentException("host cannot be null");
+        }
+        this.host = host;
+        this.boundHosts = boundHosts;
+        this.name = name;
+        this.version = version;
+        this.roles = roles;
+    }
+
+    /**
+     * Create a {@linkplain Node} without any metadata.
+     */
+    public Node(HttpHost host) {
+        this(host, null, null, null, null);
+    }
+
+    /**
+     * Make a copy of this {@link Node} but replacing its
+     * {@link #getHost() host}. Use this when the sniffing implementation
+     * returns a {@link #getHost() host} that is not useful to the client.
+     */
+    public Node withHost(HttpHost host) {
+        /*
+         * If the new host isn't in the bound hosts list we add it so the
+         * result looks sane.
+         */
+        Set<HttpHost> boundHosts = this.boundHosts;
+        if (false == boundHosts.contains(host)) {
+            boundHosts = new HashSet<>(boundHosts);
+            boundHosts.add(host);
+            boundHosts = unmodifiableSet(boundHosts);
+        }
+        return new Node(host, boundHosts, name, version, roles);
+    }
+
+    /**
+     * Contact information for the host.
+     */
+    public HttpHost getHost() {
+        return host;
+    }
+
+    /**
+     * Addresses on which the host is listening. These are useful to have
+     * around because they allow you to find a host based on any address it
+     * is listening on.
+     */
+    public Set<HttpHost> getBoundHosts() {
+        return boundHosts;
+    }
+
+    /**
+     * @return the name
+     */
+    public String getName() {
+        return name;
+    }
+
+    /**
+     * Version of Elasticsearch that the node is running or {@code null}
+     * if we don't know the version.
+     */
+    public String getVersion() {
+        return version;
+    }
+
+    /**
+     * Roles that the Elasticsearch process on the host has or {@code null}
+     * if we don't know what roles the node has.
+     */
+    public Roles getRoles() {
+        return roles;
+    }
+
+    @Override
+    public String toString() {
+        StringBuilder b = new StringBuilder();
+        b.append("[host=").append(host);
+        if (boundHosts != null) {
+            b.append(", bound=").append(boundHosts);
+        }
+        if (name != null) {
+            b.append(", name=").append(name);
+        }
+        if (version != null) {
+            b.append(", version=").append(version);
+        }
+        if (roles != null) {
+            b.append(", roles=").append(roles);
+        }
+        return b.append(']').toString();
+    }
+
+    @Override
+    public boolean equals(Object obj) {
+        if (obj == null || obj.getClass() != getClass()) {
+            return false;
+        }
+        Node other = (Node) obj;
+        return host.equals(other.host)
+            && Objects.equals(boundHosts, other.boundHosts)
+            && Objects.equals(version, other.version)
+            && Objects.equals(name, other.name)
+            && Objects.equals(roles, other.roles);
+    }
+
+    @Override
+    public int hashCode() {
+        return Objects.hash(host, boundHosts, name, version, roles);
+    }
+
+    /**
+     * Role information about an Elasticsearch process.
+     */
+    public static final class Roles {
+        private final boolean masterEligible;
+        private final boolean data;
+        private final boolean ingest;
+
+        public Roles(boolean masterEligible, boolean data, boolean ingest) {
+            this.masterEligible = masterEligible;
+            this.data = data;
+            this.ingest = ingest;
+        }
+
+        /**
+         * The node <strong>could</strong> be elected master.
+         */
+        public boolean isMasterEligible() {
+            return masterEligible;
+        }
+        /**
+         * The node stores data.
+         */
+        public boolean isData() {
+            return data;
+        }
+        /**
+         * The node runs ingest pipelines.
+         */
+        public boolean isIngest() {
+            return ingest;
+        }
+
+        @Override
+        public String toString() {
+            StringBuilder result = new StringBuilder(3);
+            if (masterEligible) result.append('m');
+            if (data) result.append('d');
+            if (ingest) result.append('i');
+            return result.toString();
+        }
+
+        @Override
+        public boolean equals(Object obj) {
+            if (obj == null || obj.getClass() != getClass()) {
+                return false;
+            }
+            Roles other = (Roles) obj;
+            return masterEligible == other.masterEligible
+                && data == other.data
+                && ingest == other.ingest;
+        }
+
+        @Override
+        public int hashCode() {
+            return Objects.hash(masterEligible, data, ingest);
+        }
+    }
+}