Include cluster statistics on search response (#3601)

* Include cluster statistics on search response

This commit includes cluster statistics returned on a search response
under the key _clusters when a cross cluster search is performed.

Closes #3512

(cherry picked from commit ec32967)

Author: russcam

src/Nest/CommonOptions/Hit/ShardStatistics.cs

@@ -18,4 +18,16 @@ public class ShardStatistics
 		[DataMember(Name = "total")]
 		public int Total { get; internal set; }
 	}
+
+	public class ClusterStatistics
+	{
+		[DataMember(Name = "skipped")]
+		public int Skipped { get; internal set; }
+
+		[DataMember(Name = "successful")]
+		public int Successful { get; internal set; }
+
+		[DataMember(Name = "total")]
+		public int Total { get; internal set; }
+	}
 }

src/Nest/Search/Search/SearchResponse.cs

@@ -5,16 +5,29 @@
 
 namespace Nest
 {
+	/// <summary>
+	/// A response to a search request
+	/// </summary>
+	/// <typeparam name="T">The document type</typeparam>
 	public interface ISearchResponse<T> : IResponse where T : class
 	{
 		/// <summary>
 		/// Gets the collection of aggregations
 		/// </summary>
 		AggregateDictionary Aggregations { get; }
 
+		/// <inheritdoc cref="Aggregations"/>
 		[Obsolete("Aggs has been renamed to Aggregations and will be removed in NEST 7.x")]
 		AggregateDictionary Aggs { get; }
 
+		/// <summary>
+		/// Gets the statistics about the clusters on which the search query was executed.
+		/// </summary>
+		/// <remarks>
+		/// Valid for cross cluster searches and Elasticsearch 6.1.0+
+		/// </remarks>
+		ClusterStatistics Clusters { get; }
+
 		/// <summary>
 		/// Gets the documents inside the hits, by deserializing <see cref="IHitMetadata{T}.Source" /> into <typeparamref name="T" />
 		/// <para>
@@ -70,7 +83,7 @@ public interface ISearchResponse<T> : IResponse where T : class
 		string ScrollId { get; }
 
 		/// <summary>
-		/// Gets the meta data about the shards on which the search query was executed.
+		/// Gets the statistics about the shards on which the search query was executed.
 		/// </summary>
 		ShardStatistics Shards { get; }
 
@@ -107,13 +120,18 @@ public class SearchResponse<T> : ResponseBase, ISearchResponse<T> where T : clas
 		private IReadOnlyCollection<FieldValues> _fields;
 
 		private IReadOnlyCollection<IHit<T>> _hits;
-
+		/// <inheritdoc />
 		[DataMember(Name ="aggregations")]
 		public AggregateDictionary Aggregations { get; internal set; } = AggregateDictionary.Default;
 
+		/// <inheritdoc />
 		[IgnoreDataMember]
 		public AggregateDictionary Aggs => Aggregations;
 
+		/// <inheritdoc />
+		[DataMember(Name = "_clusters")]
+		public ClusterStatistics Clusters { get; internal set; }
+
 		/// <inheritdoc />
 		[IgnoreDataMember]
 		public IReadOnlyCollection<T> Documents =>
@@ -128,43 +146,52 @@ public class SearchResponse<T> : ResponseBase, ISearchResponse<T> where T : clas
 				.Select(h => h.Fields)
 				.ToList());
 
+		/// <inheritdoc />
 		[IgnoreDataMember]
 		public IReadOnlyCollection<IHit<T>> Hits =>
 			_hits ?? (_hits = HitsMetadata?.Hits ?? EmptyReadOnly<IHit<T>>.Collection);
 
+		/// <inheritdoc />
 		[DataMember(Name ="hits")]
 		public HitsMetadata<T> HitsMetadata { get; internal set; }
 
+		/// <inheritdoc />
 		[IgnoreDataMember]
 		public double MaxScore => HitsMetadata?.MaxScore ?? 0;
 
+		/// <inheritdoc />
 		[DataMember(Name ="num_reduce_phases")]
 		public long NumberOfReducePhases { get; internal set; }
 
+		/// <inheritdoc />
 		[DataMember(Name ="profile")]
 		public Profile Profile { get; internal set; }
 
-		/// <summary>
-		/// Only set when search type = scan and scroll specified
-		/// </summary>
+		/// <inheritdoc />
 		[DataMember(Name = "_scroll_id")]
 		public string ScrollId { get; internal set; }
 
+		/// <inheritdoc />
 		[DataMember(Name ="_shards")]
 		public ShardStatistics Shards { get; internal set; }
 
+		/// <inheritdoc />
 		[DataMember(Name ="suggest")]
 		public SuggestDictionary<T> Suggest { get; internal set; } = SuggestDictionary<T>.Default;
 
+		/// <inheritdoc />
 		[DataMember(Name ="terminated_early")]
 		public bool TerminatedEarly { get; internal set; }
 
+		/// <inheritdoc />
 		[DataMember(Name ="timed_out")]
 		public bool TimedOut { get; internal set; }
 
+		/// <inheritdoc />
 		[DataMember(Name ="took")]
 		public long Took { get; internal set; }
 
+		/// <inheritdoc />
 		[IgnoreDataMember]
 		public long Total => HitsMetadata?.Total.Value ?? 0;
 	}

src/Tests/Tests.Core/ManagedElasticsearch/Clusters/CrossClusterSearchCluster.cs

@@ -0,0 +1,20 @@
+using Tests.Core.ManagedElasticsearch.NodeSeeders;
+
+namespace Tests.Core.ManagedElasticsearch.Clusters
+{
+	public class CrossClusterSearchCluster : ClientTestClusterBase
+	{
+		protected override void SeedCluster()
+		{
+			new DefaultSeeder(Client).SeedNode();
+
+			// persist settings for cross cluster search, when cluster_two is not available
+			Client.ClusterPutSettings(s => s
+				.Persistent(d => d
+					.Add("cluster.remote.cluster_two.seeds", new [] { "127.0.0.1:9399" })
+					.Add("cluster.remote.cluster_two.skip_unavailable", true)
+				)
+			);
+		}
+	}
+}

src/Tests/Tests/Search/Search/SearchApiTests.cs

@@ -503,4 +503,53 @@ protected override void ExpectResponse(IListTasksResponse response)
 			}
 		}
 	}
+
+	[SkipVersion("<6.1.0", "_clusters on response only available in 6.1.0+")]
+	public class CrossClusterSearchApiTests
+		: ApiIntegrationTestBase<CrossClusterSearchCluster, ISearchResponse<Project>, ISearchRequest, SearchDescriptor<Project>, SearchRequest<Project>>
+	{
+		public CrossClusterSearchApiTests(CrossClusterSearchCluster cluster, EndpointUsage usage) : base(cluster, usage) { }
+
+		protected override bool ExpectIsValid => true;
+
+		protected override object ExpectJson => new
+		{
+			query = new
+			{
+				match_all = new { }
+			}
+		};
+
+		protected override int ExpectStatusCode => 200;
+
+		protected override Func<SearchDescriptor<Project>, ISearchRequest> Fluent => s => s
+			.Index(Nest.Indices.Index<Project>().And("cluster_two:project"))
+			.Query(q => q
+				.MatchAll()
+			);
+
+		protected override HttpMethod HttpMethod => HttpMethod.POST;
+
+		protected override SearchRequest<Project> Initializer => new SearchRequest<Project>(Nest.Indices.Index<Project>().And("cluster_two:project"))
+		{
+			Query = new QueryContainer(new MatchAllQuery())
+		};
+
+		protected override string UrlPath => $"/project%2Ccluster_two%3Aproject/doc/_search";
+
+		protected override LazyResponses ClientUsage() => Calls(
+			(c, f) => c.Search(f),
+			(c, f) => c.SearchAsync(f),
+			(c, r) => c.Search<Project>(r),
+			(c, r) => c.SearchAsync<Project>(r)
+		);
+
+		protected override void ExpectResponse(ISearchResponse<Project> response)
+		{
+			response.Clusters.Should().NotBeNull();
+			response.Clusters.Total.Should().Be(2);
+			response.Clusters.Skipped.Should().Be(1);
+			response.Clusters.Successful.Should().Be(1);
+		}
+	}
 }