Add ThreadPoolPatterns property to RouteValues

Minor amendments to documentation

Author: russcam

docs/aggregations-usage.asciidoc

@@ -8,6 +8,8 @@ If you wish to submit a PR for any spelling mistakes, typos or grammatical error
 please modify the original csharp file found at the link and submit the PR with that change. Thanks!
 ////
 
+include::aggregations/bucket/adjacency-matrix/adjacency-matrix-usage.asciidoc[]
+
 include::aggregations/bucket/children/children-aggregation-mapping.asciidoc[]
 
 include::aggregations/bucket/children/children-aggregation-usage.asciidoc[]

docs/aggregations.asciidoc

@@ -16,6 +16,8 @@ please modify the original csharp file found at the link and submit the PR with
 Aggregations are arguably one of the most powerful features of Elasticsearch and NEST
 exposes all of the available Aggregation types
 
+* <<adjacency-matrix-usage,Adjacency Matrix Usage>>
+
 * <<children-aggregation-usage,Children Aggregation Usage>>
 
 * <<date-histogram-aggregation-usage,Date Histogram Aggregation Usage>>

docs/client-concepts/connection-pooling/sniffing/role-detection.asciidoc

@@ -30,14 +30,14 @@ var audit = new Auditor(() => Framework.Cluster
     .AllDefaults()
 )
 {
-    AssertPoolBeforeCall = (pool) =>
+    AssertPoolBeforeStartup = (pool) =>
     {
         pool.Should().NotBeNull();
         pool.Nodes.Should().HaveCount(10);
         pool.Nodes.Where(n => n.HoldsData).Should().HaveCount(10);
     },
 
-    AssertPoolAfterCall = (pool) =>
+    AssertPoolAfterStartup = (pool) =>
     {
         pool.Should().NotBeNull();
         pool.Nodes.Should().HaveCount(8);
@@ -59,7 +59,7 @@ var audit = new Auditor(() => Framework.Cluster
     .AllDefaults()
 )
 {
-    AssertPoolBeforeCall = (pool) =>
+    AssertPoolBeforeStartup = (pool) =>
     {
         pool.Should().NotBeNull();
         pool.Nodes.Should().HaveCount(10);
@@ -68,10 +68,10 @@ var audit = new Auditor(() => Framework.Cluster
         pool.Nodes.Should().OnlyContain(n => n.Uri.Host == "localhost");
     },
 
-    AssertPoolAfterCall = (pool) =>
+    AssertPoolAfterStartup = (pool) =>
     {
         pool.Should().NotBeNull();
-        pool.Nodes.Should().HaveCount(7, "we filtered the node that stores no data");
+        pool.Nodes.Should().HaveCount(7, "we filtered the node that has no http enabled");
         pool.Nodes.Should().NotContain(n=>n.Uri.Port == 9201);
         pool.Nodes.Where(n => n.HoldsData).Should().HaveCount(5);
     }
@@ -80,6 +80,199 @@ var audit = new Auditor(() => Framework.Cluster
 await audit.TraceStartup();
 ----
 
+[source,csharp]
+----
+var masterNodes = new[] {9200, 9201, 9202};
+
+var totalNodesInTheCluster = 20;
+
+var audit = new Auditor(() => Framework.Cluster
+    .MasterOnlyNodes(masterNodes.Length)
+    // When the client sniffs on startup we see the cluster is 20 nodes in total
+    .Sniff(s => s.SucceedAlways()
+        .Succeeds(Always, Framework.Cluster.Nodes(totalNodesInTheCluster).StoresNoData(masterNodes).MasterEligible(masterNodes))
+    )
+    .SniffingConnectionPool()
+    .Settings(s=>s.DisablePing()) //for testing simplicity we disable pings
+)
+{
+    // before the sniff assert we only see three master only nodes
+    AssertPoolBeforeStartup = (pool) =>
+    {
+        pool.Should().NotBeNull();
+        pool.Nodes.Should().HaveCount(3, "we seeded 3 master only nodes at the start of the application");
+        pool.Nodes.Where(n => n.HoldsData).Should().HaveCount(0, "none of which hold data");
+    },
+    // after sniff assert we now know about the existence of 20 nodes.
+    AssertPoolAfterStartup = (pool) =>
+    {
+        pool.Should().NotBeNull();
+        var nodes = pool.CreateView().ToList();
+        nodes.Count().Should().Be(20, "Master nodes are included in the registration of nodes since we still favor sniffing on them");
+    }
+};
+
+var nodes = pool.CreateView().ToList();
+
+audit = await audit.TraceStartup(new ClientCall
+{
+    { SniffSuccess, 9200},
+    { HealthyResponse, 9203}
+});
+
+var seenNodes = new HashSet<int>();
+----
+
+[source,csharp]
+----
+var audit = new Auditor(() => Framework.Cluster
+    .Nodes(10)
+    .Sniff(s => s.Fails(Always))
+    .Sniff(s => s.OnPort(9202)
+        .Succeeds(Always, Framework.Cluster.Nodes(8).MasterEligible(9200, 9201, 9202))
+    )
+    .SniffingConnectionPool()
+    .AllDefaults()
+)
+{
+    AssertPoolBeforeStartup = (pool) =>
+    {
+        pool.Should().NotBeNull();
+        pool.Nodes.Should().HaveCount(10);
+        pool.Nodes.Where(n => n.MasterEligible).Should().HaveCount(10);
+    },
+    AssertPoolAfterStartup = (pool) =>
+    {
+        pool.Should().NotBeNull();
+        pool.Nodes.Should().HaveCount(8);
+        pool.Nodes.Where(n => n.MasterEligible).Should().HaveCount(3);
+    }
+};
+await audit.TraceStartup();
+----
+
+[source,csharp]
+----
+foreach (var _ in Enumerable.Range(0, 1000))
+{
+    audit = await audit.TraceCalls(
+        new ClientCall {{HealthyResponse, (a) =>
+        {
+            var port = a.Node.Uri.Port;
+            masterNodes.Should().NotContain(port);
+            seenNodes.Add(port);
+        }}}
+    );
+}
+
+seenNodes.Should().HaveCount(totalNodesInTheCluster - masterNodes.Length);
+----
+
+[source,csharp]
+----
+var totalNodesInTheCluster = 20;
+
+var setting = "node.attr.rack_id";
+
+var value = "rack_one";
+
+var nodesInRackOne = new[] {9204, 9210, 9213};
+
+var audit = new Auditor(() => Framework.Cluster
+    .Nodes(totalNodesInTheCluster)
+    // When the client sniffs on startup we see the cluster is still 20 nodes in total
+    // However we are now aware of the actual configured settings on the nodes
+    .Sniff(s => s.SucceedAlways()
+        .Succeeds(Always, Framework.Cluster.Nodes(totalNodesInTheCluster).HasSetting(setting, value, nodesInRackOne))
+    )
+    .SniffingConnectionPool()
+    .Settings(s=>s
+        .DisablePing() //for testing simplicity we disable pings
+        //We only want to execute API calls to nodes in rack_one
+        .NodePredicate(node=>node.Settings.ContainsKey(setting) && node.Settings[setting] == value)
+    )
+)
+{
+    AssertPoolAfterStartup = (pool) =>
+    {
+        pool.Should().NotBeNull();
+        var nodes = pool.CreateView().ToList();
+        nodes.Count(n => n.Settings.ContainsKey(setting)).Should().Be(3, "only three nodes are in rack_one");
+    }
+};
+
+var nodes = pool.CreateView().ToList();
+
+audit = await audit.TraceStartup(new ClientCall
+{
+    { SniffSuccess, 9200},
+    { HealthyResponse, 9204}
+});
+
+var seenNodes = new HashSet<int>();
+----
+
+[source,csharp]
+----
+foreach (var _ in Enumerable.Range(0, 1000))
+{
+    audit = await audit.TraceCalls(
+        new ClientCall {{HealthyResponse, (a) =>
+        {
+            var port = a.Node.Uri.Port;
+            nodesInRackOne.Should().Contain(port);
+            seenNodes.Add(port);
+        }}}
+    );
+}
+
+seenNodes.Should().HaveCount(nodesInRackOne.Length);
+----
+
+[source,csharp]
+----
+var totalNodesInTheCluster = 20;
+
+var audit = new Auditor(() => Framework.Cluster
+    .Nodes(totalNodesInTheCluster)
+    .Sniff(s => s.SucceedAlways()
+        .Succeeds(Always, Framework.Cluster.Nodes(totalNodesInTheCluster))
+    )
+    .SniffingConnectionPool()
+    .Settings(s => s
+        .DisablePing()
+        // evil predicate that declines ALL nodes
+        .NodePredicate(node => false)
+    )
+);
+
+await audit.TraceUnexpectedElasticsearchException(new ClientCall
+{
+    { SniffOnStartup }, //audit logs we are sniffing for the very very first time one startup
+    { SniffSuccess }, //this goes ok because we ignore predicate when sniffing
+    { NoNodesAttempted } //when trying to do an actual API call the predicate prevents any nodes from being attempted
+}, e =>
+{
+    e.FailureReason.Should().Be(PipelineFailure.Unexpected);
+    //generating the debug information should not throw
+    Func<string> debug = () => e.DebugInformation;
+    debug.Invoking(s =>s()).ShouldNotThrow();
+    /* EXAMPLE OF PREVIOUS
+# FailureReason: Unrecoverable/Unexpected NoNodesAttempted while attempting POST on default-index/project/_search on an empty node, likely a node predicate on ConnectionSettings not matching ANY nodes
+ - [1] SniffOnStartup: Took: 00:00:00
+ - [2] SniffSuccess: Node: http://localhost:9200/ Took: 00:00:00
+ - [3] NoNodesAttempted: Took: 00:00:00
+# Inner Exception: No nodes were attempted, this can happen when a node predicate does not match any nodes
+    */
+});
+
+e.FailureReason.Should().Be(PipelineFailure.Unexpected);
+
+Func<string> debug = () => e.DebugInformation;
+
+debug.Invoking(s =>s()).ShouldNotThrow();
+----
+
 [source,csharp]
 ----
 var audit = new Auditor(() => Framework.Cluster
@@ -91,15 +284,15 @@ var audit = new Auditor(() => Framework.Cluster
     .AllDefaults()
 )
 {
-    AssertPoolBeforeCall = (pool) =>
+    AssertPoolBeforeStartup = (pool) =>
     {
         pool.Should().NotBeNull();
         pool.Nodes.Should().HaveCount(10);
         pool.Nodes.Where(n => n.HoldsData).Should().HaveCount(10);
         pool.Nodes.Should().OnlyContain(n => n.Uri.Host == "localhost");
     },
 
-    AssertPoolAfterCall = (pool) =>
+    AssertPoolAfterStartup = (pool) =>
     {
         pool.Should().NotBeNull();
         pool.Nodes.Should().HaveCount(8);
@@ -119,11 +312,15 @@ node.MasterEligible.Should().BeTrue();
 
 node.HoldsData.Should().BeFalse();
 
+node.Settings.Should().NotBeEmpty().And.Contain("node.attr.rack_id", "rack_one");
+
 node = await SniffAndReturnNodeAsync();
 
 node.MasterEligible.Should().BeTrue();
 
 node.HoldsData.Should().BeFalse();
+
+node.Settings.Should().NotBeEmpty().And.Contain("node.attr.rack_id", "rack_one");
 ----
 
 [source,csharp]
@@ -159,31 +356,3 @@ nodes.Should().NotBeEmpty().And.HaveCount(1);
 var node = nodes.First();
 ----
 
-[source,csharp]
-----
-var audit = new Auditor(() => Framework.Cluster
-    .Nodes(10)
-    .Sniff(s => s.Fails(Always))
-    .Sniff(s => s.OnPort(9202)
-        .Succeeds(Always, Framework.Cluster.Nodes(8).MasterEligible(9200, 9201, 9202))
-    )
-    .SniffingConnectionPool()
-    .AllDefaults()
-)
-{
-    AssertPoolBeforeCall = (pool) =>
-    {
-        pool.Should().NotBeNull();
-        pool.Nodes.Should().HaveCount(10);
-        pool.Nodes.Where(n => n.MasterEligible).Should().HaveCount(10);
-    },
-    AssertPoolAfterCall = (pool) =>
-    {
-        pool.Should().NotBeNull();
-        pool.Nodes.Should().HaveCount(8);
-        pool.Nodes.Where(n => n.MasterEligible).Should().HaveCount(3);
-    }
-};
-await audit.TraceStartup();
-----
-