From 56e09a16bdc8443521d5d19ace3244d5fbb46d36 Mon Sep 17 00:00:00 2001 From: Marci W <333176+marciw@users.noreply.github.com> Date: Sat, 9 Aug 2025 08:41:02 -0400 Subject: [PATCH 1/5] Fix class name; edit for clarity, progressive structure --- .../rest5-client/config/basic_authentication.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/docs/reference/transport/rest5-client/config/basic_authentication.md b/docs/reference/transport/rest5-client/config/basic_authentication.md index 2e8f99756..661143580 100644 --- a/docs/reference/transport/rest5-client/config/basic_authentication.md +++ b/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). From 15b23a98d40bb40d912f6a32327fb89d0d7cb333 Mon Sep 17 00:00:00 2001 From: Marci W <333176+marciw@users.noreply.github.com> Date: Sat, 9 Aug 2025 12:29:56 -0400 Subject: [PATCH 2/5] use ConnectionConfig; other cleanup --- .../transport/rest5-client/config/timeouts.md | 31 ++++++++++++------- 1 file changed, 20 insertions(+), 11 deletions(-) diff --git a/docs/reference/transport/rest5-client/config/timeouts.md b/docs/reference/transport/rest5-client/config/timeouts.md index 4151dfcee..8d1f34d71 100644 --- a/docs/reference/transport/rest5-client/config/timeouts.md +++ b/docs/reference/transport/rest5-client/config/timeouts.md @@ -1,26 +1,36 @@ - # 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 **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 `setHttpClientConfigCallback` and `setRequestConfigCallback` while building the `Rest5Client`. The following example sets a 10-second connect 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> + .setHttpClientConfigCallback(c -> c.setDefaultConnectionConfig( + ConnectionConfig.custom() + .setConnectTimeout(Timeout.ofSeconds(10)) + .build() + )) .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 +40,3 @@ RequestOptions options = RequestOptions.DEFAULT.toBuilder() ElasticsearchTransport transport = new Rest5ClientTransport( restClient, new JacksonJsonpMapper(), options); ``` - From cb4261c1457ef0bc8ed96f68a50daba39787927c Mon Sep 17 00:00:00 2001 From: Marci W <333176+marciw@users.noreply.github.com> Date: Mon, 11 Aug 2025 17:48:30 -0400 Subject: [PATCH 3/5] Update docs/reference/transport/rest5-client/config/timeouts.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- docs/reference/transport/rest5-client/config/timeouts.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/transport/rest5-client/config/timeouts.md b/docs/reference/transport/rest5-client/config/timeouts.md index 8d1f34d71..60525d54f 100644 --- a/docs/reference/transport/rest5-client/config/timeouts.md +++ b/docs/reference/transport/rest5-client/config/timeouts.md @@ -11,7 +11,7 @@ To configure timeouts, use `setHttpClientConfigCallback` and `setRequestConfigCa % :::{include-code} src={{doc-tests-src}}/rest5_client/RestClientDocumentation.java tag=rest-client-config-timeouts ```java Rest5ClientBuilder builder = Rest5Client - .builder(new HttpHost("http", "localhost", 9200)) <1> + .builder(new HttpHost("localhost", 9200, "http")) <1> .setHttpClientConfigCallback(c -> c.setDefaultConnectionConfig( ConnectionConfig.custom() .setConnectTimeout(Timeout.ofSeconds(10)) From 86971b1517164ba3d04b15ccf0c43106ccfebfc9 Mon Sep 17 00:00:00 2001 From: Marci W <333176+marciw@users.noreply.github.com> Date: Thu, 14 Aug 2025 09:17:41 -0400 Subject: [PATCH 4/5] Address review feedback --- .../transport/rest5-client/config/timeouts.md | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/docs/reference/transport/rest5-client/config/timeouts.md b/docs/reference/transport/rest5-client/config/timeouts.md index 60525d54f..b657bf4e0 100644 --- a/docs/reference/transport/rest5-client/config/timeouts.md +++ b/docs/reference/transport/rest5-client/config/timeouts.md @@ -3,20 +3,19 @@ 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 idle time waiting 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 `setHttpClientConfigCallback` and `setRequestConfigCallback` while building the `Rest5Client`. The following example sets a 10-second connect timeout and a 20-second response timeout: +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, "http")) <1> - .setHttpClientConfigCallback(c -> c.setDefaultConnectionConfig( - ConnectionConfig.custom() - .setConnectTimeout(Timeout.ofSeconds(10)) - .build() - )) + .builder(new HttpHost("http", "localhost", 9200)) <1> + .setConnectionConfigCallback(connectConf -> connectConf + .setConnectTimeout(Timeout.ofSeconds(10)) + .setSocketTimeout(Timeout.ofSeconds(10))) .setRequestConfigCallback(r -> r .setResponseTimeout(Timeout.ofSeconds(20)) ); From fdd90ab0b34d416e0afc1411ae3ba10ae5581fef Mon Sep 17 00:00:00 2001 From: Marci W <333176+marciw@users.noreply.github.com> Date: Thu, 14 Aug 2025 09:20:27 -0400 Subject: [PATCH 5/5] grammar is nice --- docs/reference/transport/rest5-client/config/timeouts.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/transport/rest5-client/config/timeouts.md b/docs/reference/transport/rest5-client/config/timeouts.md index b657bf4e0..e80dde9ee 100644 --- a/docs/reference/transport/rest5-client/config/timeouts.md +++ b/docs/reference/transport/rest5-client/config/timeouts.md @@ -3,7 +3,7 @@ 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 idle time waiting for I/O on an established socket. The socket 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`.