Merge pull request #1047 from marciw/mw-rest5

[DOCS] Rest 5 client fixes

Author: marciw

docs/reference/transport/rest5-client/config/basic_authentication.md

@@ -1,7 +1,7 @@
 
 # Basic authentication
 
-Configuring basic authentication can be done by providing an `HttpClientConfigCallback` while building the `RestClient` through its builder. The interface has one method that receives an instance of [`org.apache.http.impl.nio.client.HttpAsyncClientBuilder`](https://hc.apache.org/httpcomponents-asyncclient-4.1.x/current/httpasyncclient/apidocs/org/apache/http/impl/nio/client/HttpAsyncClientBuilder.html) as an argument and has the same return type. The http client builder can be modified and then returned. In the following example we set a default credentials provider that requires basic authentication.
+To use basic authentication in the REST 5 client, set a default authorization header:
 
 % :::{include-code} src={{doc-tests-src}}/rest5_client/RestClientDocumentation.java tag=rest-client-config-basic-auth
 ```java
@@ -16,7 +16,9 @@ Rest5ClientBuilder restClient = Rest5Client
 
 ```
 
-Preemptive Authentication can be disabled, which means that every request will be sent without authorization headers to see if it is accepted and, upon receiving an HTTP 401 response, it will resend the exact same request with the basic authentication header. If you wish to do this, then you can do so by disabling it via the `HttpClientConfigCallback`:
+To configure authentication behavior, pass an `HttpClientConfigCallback` when building the `Rest5Client`. The callback's single method takes an instance of [`org.apache.hc.client5.http.impl.async.HttpAsyncClientBuilder`](https://hc.apache.org/httpcomponents-client-5.5.x/current/httpclient5/apidocs/org/apache/hc/client5/http/impl/async/HttpAsyncClientBuilder.html) as an argument and returns the same type, so you can modify the provided builder and return it for the client to use.
+
+By default, the HTTP client uses preemptive authentication: it includes credentials in the initial request. You might want to use non-preemptive authentication, which sends a request without credentials and retries with the header after a `401 Unauthorized` challenge. To do this, set an `HttpClientConfigCallback` with auth caching disabled:
 
 % :::{include-code} src={{doc-tests-src}}/rest5_client/RestClientDocumentation.java tag=rest-client-config-disable-preemptive-auth
 ```java
@@ -26,12 +28,12 @@ var creds = Base64.getEncoder().encodeToString("user:test-user-password".getByte
 
 Rest5ClientBuilder restClient = Rest5Client
     .builder(new HttpHost("https", "localhost", 9200))
-    .setHttpClientConfigCallback(HttpAsyncClientBuilder::disableAuthCaching)
+    .setHttpClientConfigCallback(HttpAsyncClientBuilder::disableAuthCaching) <1>
     .setDefaultHeaders(new Header[]{
         new BasicHeader("Authorization", "Basic " + creds)
     });
 ```
 
-1. Disable preemptive authentication
-
+1. Disables preemptive authentication
 
+For more options, refer to [](other_authentication_methods.md).

docs/reference/transport/rest5-client/config/timeouts.md

@@ -1,26 +1,35 @@
-
 # Timeouts
 
-Configuring requests timeouts can be done by using the `setRequestConfigCallback` method while building the `RestClient`. In the following example we increase the connect timeout (defaults to 30 second) and the response timeout (defaults to 0, which is infinite).
+You can set timeouts when building the `Rest5Client`:
+
+- The **connect timeout** is the maximum time for establishing a TCP connection, including the TLS handshake. The connect timeout is set on `ConnectionConfig`.
+- The **socket timeout** is the maximum time to wait for I/O on an established socket. The socket timeout is set on `ConnectionConfig`.
+- The **response timeout** is the maximum period to wait for response data. The response timeout is set on `RequestConfig`. 
+- The **connection request timeout** is the maximum time for leasing a connection from the pool. The connection request timeout is set on `RequestConfig`. 
+
+To configure timeouts, use `setConnectionConfigCallback` and `setRequestConfigCallback` while building the `Rest5Client`. The following example sets a 10-second connect timeout, a 10-second socket timeout, and a 20-second response timeout:
 
 % :::{include-code} src={{doc-tests-src}}/rest5_client/RestClientDocumentation.java tag=rest-client-config-timeouts
 ```java
 Rest5ClientBuilder builder = Rest5Client
-    .builder(new HttpHost("localhost", 9200))
+    .builder(new HttpHost("http", "localhost", 9200)) <1>
+    .setConnectionConfigCallback(connectConf -> connectConf
+        .setConnectTimeout(Timeout.ofSeconds(10))
+        .setSocketTimeout(Timeout.ofSeconds(10)))
     .setRequestConfigCallback(r -> r
-        .setConnectTimeout(Timeout.of(5000, TimeUnit.MILLISECONDS))
-        .setResponseTimeout(Timeout.of(30000, TimeUnit.MILLISECONDS))
-        .build()
+        .setResponseTimeout(Timeout.ofSeconds(20))
     );
 ```
 
-Timeouts also can be set per request with RequestOptions, which overrides RestClient's builder. The RequestOptions can then be set in the Rest5ClientTransport constructor.
+1. Specify `https` for TLS.
+
+You can also set per-request timeouts using `RequestOptions`, which override the builder defaults. The following example sets a response timeout of 60 seconds, as well as a connection request timeout of 1 second (to limit pooled connection wait time):
 
 % :::{include-code} src={{doc-tests-src}}/rest5_client/RestClientDocumentation.java tag=rest-client-config-request-options-timeouts
 ```java
-RequestConfig requestConfig = RequestConfig.custom()
-    .setConnectTimeout(Timeout.ofMilliseconds(5000))
-    .setConnectionRequestTimeout(Timeout.ofMilliseconds(60000))
+RequestConfig requestConfig = RequestConfig.custom()   
+    .setResponseTimeout(Timeout.ofSeconds(60))
+    .setConnectionRequestTimeout(Timeout.ofSeconds(1))
     .build();
 
 RequestOptions options = RequestOptions.DEFAULT.toBuilder()
@@ -30,4 +39,3 @@ RequestOptions options = RequestOptions.DEFAULT.toBuilder()
 ElasticsearchTransport transport = new Rest5ClientTransport(
     restClient, new JacksonJsonpMapper(), options);
 ```
-