gnodet-bot commented on code in PR #30208:
URL: https://github.com/apache/camel/pull/30208#discussion_r4586737669


##########
components/camel-http/src/main/docs/http-component.adoc:
##########
@@ -504,28 +504,42 @@ Camel error handler sends it again. Set the timeouts to 
what your service needs:
 
https://api.example.com/orders?connectTimeout=5000&soTimeout=30000&connectionRequestTimeout=5000
 ----
 
-NOTE: `soTimeout` and `connectionTimeToLive` are settings of the connection 
pool that the component creates for the
-endpoint: they do not apply when you set your own `clientConnectionManager` on 
the component.
+NOTE: `soTimeout`, `connectionTimeToLive`, `connectionIdleTimeout` and 
`validateAfterInactivity` are settings of the
+connection pool that the component creates for the endpoint: they do not apply 
when you set your own
+`clientConnectionManager` on the component.
 
 ==== Pooled connections closed by the server or by a NAT
 
 The endpoint keeps connections open for reuse. Before reusing a connection 
that has been idle for more than
-2 seconds, HttpClient checks that the server has not closed it (its 
`validateAfterInactivity`, which the component does
-not expose). A request sent sooner on a connection that the server closed 
fails with `NoHttpResponseException`.
+`validateAfterInactivity` (component option, milliseconds, 2 seconds by 
default), HttpClient checks that the server has
+not closed it. A request sent sooner on a connection that the server closed 
fails with `NoHttpResponseException`.
 HttpClient retries it once only when the method is idempotent (`GET`, `HEAD`, 
`PUT`, `DELETE`, `OPTIONS`, `TRACE`), so
-a `POST` or a `PATCH` fails and needs a redelivery of the Camel error handler.
-
-A NAT or firewall that drops an idle connection silently does not close it, so 
the pool cannot see it: the next
-request on it waits for the read timeout and fails, without a retry by 
HttpClient. To keep the pool from reusing such a
-connection:
-
+a `POST` or a `PATCH` fails and needs a redelivery of the Camel error handler. 
With `validateAfterInactivity=0`,
+HttpClient checks the connection before each reuse, which costs a read of up 
to 1 millisecond per request; a negative
+value turns the check off.
+
+A NAT, firewall or load balancer that drops an idle connection silently does 
not close it, so neither the pool nor the
+check above can see it: the next request on it waits for the read timeout and 
fails, without a retry by HttpClient. To
+keep the pool from reusing such a connection:
+
+* `connectionIdleTimeout` (component option, milliseconds): the maximum time a 
connection can stay idle in the pool and
+still be reused; a connection idle for longer is closed when it would be 
reused, and the request opens a new one. It
+applies whatever `Keep-Alive` timeout the server announces. Not set by 
default. Set it below the idle timeout of the
+NAT, firewall or load balancer.
 * `httpClient.connectionKeepAlive` (milliseconds): how long an idle connection 
is kept for reuse when the response of
 the server has no `Keep-Alive` header with a timeout; 3 minutes by default. 
Set it below the idle timeout of the NAT or
-firewall.
+firewall: it does not help when the server announces a longer timeout.
 * `connectionTimeToLive` (component option, milliseconds): the maximum age of 
a connection, counted from its creation,
 whether it was busy or idle. Below the idle timeout of the NAT or firewall it 
works too, at the cost of reconnecting
 busy connections as well.
 
+For example, in `application.properties`, for a NAT that drops connections 
idle for 5 minutes:
+
+[source,properties]
+----
+camel.component.https.connection-idle-timeout=240000

Review Comment:
   💡 **Suggestion:** The example only shows the HTTPS component property. 
Consider adding the HTTP (plain) variant as well, so users configuring plain 
HTTP endpoints know what to set:
   
   ```suggestion
   camel.component.https.connection-idle-timeout=240000
   camel.component.http.connection-idle-timeout=240000
   ```



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: [email protected]

For queries about this service, please contact Infrastructure at:
[email protected]

Reply via email to