update documentation

Author: Mpdreamz

docs/aggregations/writing-aggregations.asciidoc

@@ -98,13 +98,14 @@ new SearchRequest<Project>
 {
     Aggregations = new AggregationDictionary
     {
-        { "name_of_child_agg", new ChildrenAggregation("name_of_child_agg", typeof(CommitActivity))
+        {
+            "name_of_child_agg", new ChildrenAggregation("name_of_child_agg", typeof(CommitActivity))
             {
                 Aggregations = new AggregationDictionary
                 {
-                    { "average_per_child", new AverageAggregation("average_per_child", "confidenceFactor") },
-                    { "max_per_child", new MaxAggregation("max_per_child", "confidenceFactor") },
-                    { "min_per_child", new MinAggregation("min_per_child", "confidenceFactor") },
+                    {"average_per_child", new AverageAggregation("average_per_child", "confidenceFactor")},
+                    {"max_per_child", new MaxAggregation("max_per_child", "confidenceFactor")},
+                    {"min_per_child", new MinAggregation("min_per_child", "confidenceFactor")},
                 }
             }
         }
@@ -143,52 +144,91 @@ Now that's much cleaner! Assigning an `*Aggregation` type directly to the `Aggre
  on a search request works because there are implicit conversions within NEST to handle this for you.
 
 [float]
-=== Aggregating over a collection of aggregations
+=== Mixed usage of object initializer and fluent
 
-An advanced scenario may involve an existing collection of aggregation functions that should be set as aggregations
-on the request. Using LINQ's `.Aggregate()` method, each function can be applied to the aggregation descriptor
-`childAggs` below) in turn, returning the descriptor after each function application.
+Sometimes its useful to mix and match fluent and object initializer, the fluent Aggregations method therefore
+also accepts `AggregationDictionary` directly.
 
 ==== Fluent DSL example
 
 [source,csharp]
 ----
-var aggregations = new List<Func<AggregationContainerDescriptor<CommitActivity>, IAggregationContainer>> <1>
+s => s
+.Aggregations(new ChildrenAggregation("name_of_child_agg", typeof(CommitActivity))
 {
-    a => a.Average("average_per_child", avg => avg.Field(p => p.ConfidenceFactor)),
-    a => a.Max("max_per_child", avg => avg.Field(p => p.ConfidenceFactor)),
-    a => a.Min("min_per_child", avg => avg.Field(p => p.ConfidenceFactor))
-};
+    Aggregations =
+        new AverageAggregation("average_per_child", Field<CommitActivity>(p => p.ConfidenceFactor))
+        && new MaxAggregation("max_per_child", Field<CommitActivity>(p => p.ConfidenceFactor))
+        && new MinAggregation("min_per_child", Field<CommitActivity>(p => p.ConfidenceFactor))
+})
+----
 
-return s => s
-    .Aggregations(aggs => aggs
-        .Children<CommitActivity>("name_of_child_agg", child => child
-            .Aggregations(childAggs =>
-                aggregations.Aggregate(childAggs, (acc, agg) => { agg(acc); return acc; }) <2>
-            )
-        )
-    );
+[float]
+=== Binary operators off the same descriptor
+
+For dynamic aggregation building using the fluent syntax it can be useful to abstract to methods as much as possible.
+You can use the binary operator `&&` on the same descriptor to compose the graph. Each side of the
+binary operation can return null dynamically.
+
+[source,csharp]
+----
+s => s
+.Aggregations(aggs => aggs
+    .Children<CommitActivity>("name_of_child_agg", child => child
+        .Aggregations(Combine)
+    )
+)
 ----
-<1> a list of aggregation functions to apply
-<2> Using LINQ's `Aggregate()` function to accumulate/apply all of the aggregation functions
 
-Combining multiple `AggregationDescriptor` is also possible using the bitwise `&&` operator
+[float]
+=== Returning a different AggregationContainer in fluent syntax
+
+All the fluent selector expects is an `IAggregationContainer` to be returned. You could abstract this to a
+method returning `AggregationContainer` which is free to use the object initializer syntax
+to compose that `AggregationContainer`.
+
+[source,csharp]
+----
+s => s
+.Aggregations(aggs => aggs
+    .Children<CommitActivity>("name_of_child_agg", child => child
+        .Aggregations(childAggs => Combine())
+    )
+)
+----
+
+[float]
+=== Aggregating over a collection of aggregations
+
+An advanced scenario may involve an existing collection of aggregation functions that should be set as aggregations
+on the request. Using LINQ's `.Aggregate()` method, each function can be applied to the aggregation descriptor
+`childAggs` below) in turn, returning the descriptor after each function application.
 
 [source,csharp]
 ----
-var aggregations = new AggregationContainerDescriptor<CommitActivity>()
-        .Average("average_per_child", avg => avg.Field(p => p.ConfidenceFactor))
-        .Max("max_per_child", avg => avg.Field(p => p.ConfidenceFactor))
-        && new AggregationContainerDescriptor<CommitActivity>()
-            .Min("min_per_child", avg => avg.Field(p => p.ConfidenceFactor));
+var aggregations =
+        new List<Func<AggregationContainerDescriptor<CommitActivity>, IAggregationContainer>> <1>
+        {
+            a => a.Average("average_per_child", avg => avg.Field(p => p.ConfidenceFactor)),
+            a => a.Max("max_per_child", avg => avg.Field(p => p.ConfidenceFactor)),
+            a => a.Min("min_per_child", avg => avg.Field(p => p.ConfidenceFactor))
+        };
 
 return s => s
         .Aggregations(aggs => aggs
             .Children<CommitActivity>("name_of_child_agg", child => child
-                .Aggregations(childAggs => aggregations)
+                .Aggregations(childAggs =>
+                        aggregations.Aggregate(childAggs, (acc, agg) =>
+                        {
+                            agg(acc);
+                            return acc;
+                        }) <2>
+                )
             )
         );
 ----
+<1> a list of aggregation functions to apply
+<2> Using LINQ's `Aggregate()` function to accumulate/apply all of the aggregation functions
 
 [[aggs-vs-aggregations]]
 [float]
@@ -222,7 +262,7 @@ the `Average` and `Max` sub aggregations.
 
 [source,csharp]
 ----
-response.IsValid.Should().BeTrue();
+response.ShouldBeValid();
 
 var childAggregation = response.Aggs.Children("name_of_child_agg");
 

docs/client-concepts/certificates/working-with-certificates.asciidoc

@@ -133,7 +133,7 @@ You can set Client Certificates to use on all connections on `ConnectionSettings
 ----
 public class PkiCluster : CertgenCaCluster
 {
-    public override ConnectionSettings Authenticate(ConnectionSettings s) => s <1>
+    protected override ConnectionSettings Authenticate(ConnectionSettings s) => s <1>
         .ClientCertificate(
             ClientCertificate.LoadWithPrivateKey(
                 this.Node.FileSystem.ClientCertificate, <2>

docs/client-concepts/connection-pooling/building-blocks/connection-pooling.asciidoc

@@ -241,3 +241,41 @@ client.ConnectionSettings.ConnectionPool
     .Should().BeOfType<StickyConnectionPool>();
 ----
 
+[[sticky-sniffing-connection-pool]]
+==== Sticky Sniffing Connection Pool
+
+A type of connection pool that returns the first live node to issue a request against, such that the node is _sticky_ between requests.
+This implementation supports sniffing and sorting so that each instance of your application can favor a node in the same rack based
+on node attributes for instance.
+
+[source,csharp]
+----
+var uris = Enumerable.Range(9200, 5)
+    .Select(port => new Uri($"http://localhost:{port}"));
+----
+
+a sniffing sorted sticky pool takes a second parameter `Func` takes a Node and returns a weight.
+Nodes will be sorted descending by weight. In the following example we score nodes that are client nodes
+AND in rack_id `rack_one` the highest
+
+[source,csharp]
+----
+var pool = new StickySniffingConnectionPool(uris, n =>
+    (n.ClientNode ? 10 : 0)
+    + (n.Settings.TryGetValue("node.attr.rack_id", out string rackId)
+               && rackId == "rack_one" ? 10 : 0));
+
+pool.SupportsReseeding.Should().BeTrue();
+pool.SupportsPinging.Should().BeTrue();
+----
+
+To create a client using the sticky sniffing connection pool pass
+the connection pool to the `ConnectionSettings` you pass to `ElasticClient`
+
+[source,csharp]
+----
+var client = new ElasticClient(new ConnectionSettings(pool));
+client.ConnectionSettings.ConnectionPool
+    .Should().BeOfType<StickySniffingConnectionPool>();
+----
+

docs/client-concepts/connection-pooling/building-blocks/transports.asciidoc

@@ -15,7 +15,7 @@ please modify the original csharp file found at the link and submit the PR with
 [[transports]]
 === Transports
 
-The `ITransport` interface can be seen as the motor block of the client. Its interface is 
+The `ITransport` interface can be seen as the motor block of the client. Its interface is
 deceitfully simple, yet it's ultimately responsible for translating a client call to a response.
 
 If for some reason you do not agree with the way we wrote the internals of the client,
@@ -51,12 +51,12 @@ custom `ITransport` implementation and if you do, {github}/issues[please let us
 var response = inMemoryTransport.Request<SearchResponse<Project>>(
     HttpMethod.GET,
     "/_search",
-    new { query = new { match_all = new { } } });
+    PostData.Serializable(new { query = new { match_all = new { } } }));
 
 response = await inMemoryTransport.RequestAsync<SearchResponse<Project>>(
     HttpMethod.GET,
     "/_search",
     default(CancellationToken),
-    new { query = new { match_all = new { } } });
+    PostData.Serializable(new { query = new { match_all = new { } } }));
 ----
 

docs/client-concepts/connection-pooling/exceptions/unrecoverable-exceptions.asciidoc

@@ -89,21 +89,21 @@ audit = await audit.TraceElasticsearchException(
 <2> Second call results in a bad response
 <3> The reason for the bad response is Bad Authentication
 
-When a bad authentication response occurs, the client does not attempt to deserialize the response body returned;
-The response may or may not have a body and even when it does, it may not even be JSON.
+When a bad authentication response occurs, the client attempts to deserialize the response body returned;
 
-In the following couple of examples, we set up a cluster that always returns a typical nginx HTML response body
-with 401 response to client calls. In this first example, we assert that the failure is because of a 401 Bad Authentication
-response but the response body is not captured on the response
+In some setups you might be running behind a proxy and you might need to prevent the client from trying to deserialize
+bad json. In the following example an HTML response is return but with an application/json content type. If the proxy is not
+under your control you would need to be able to fix this in the client. Here we make the client aware that 401 responses
+should never be deserialized by calling `SkipDeserializationForStatusCodes()` on `ConnectionSettings`.
 
 [source,csharp]
 ----
 var audit = new Auditor(() => Framework.Cluster
     .Nodes(10)
     .Ping(r => r.SucceedAlways())
-    .ClientCalls(r => r.FailAlways(401).ReturnResponse(HtmlNginx401Response)) <1>
+    .ClientCalls(r => r.FailAlways(401).ReturnByteResponse(HtmlNginx401Response, "application/json")) <1>
     .StaticConnectionPool()
-    .AllDefaults()
+    .Settings(s=>s.SkipDeserializationForStatusCodes(401))
 );
 
 audit = await audit.TraceElasticsearchException(
@@ -124,13 +124,15 @@ audit = await audit.TraceElasticsearchException(
 
 Now in this example, by turning on `DisableDirectStreaming()` on `ConnectionSettings`, we see the same behaviour exhibited
 as before, but this time however, the response body bytes are captured in the response and can be inspected.
+Also note that in this example the 401 returns the correct mime type for html so the client wont try to deserialize to json and
+we no longer need to set `SkipDeserializationForStatusCodes()`
 
 [source,csharp]
 ----
 var audit = new Auditor(() => Framework.Cluster
     .Nodes(10)
     .Ping(r => r.SucceedAlways())
-    .ClientCalls(r => r.FailAlways(401).ReturnResponse(HtmlNginx401Response))
+    .ClientCalls(r => r.FailAlways(401).ReturnByteResponse(HtmlNginx401Response, "text/html"))
     .StaticConnectionPool()
     .Settings(s => s.DisableDirectStreaming())
 );