STF-322: Document transport-failure retry in README and CHANGELOG

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: oschwald

CHANGELOG.md

@@ -1,6 +1,12 @@
 CHANGELOG
 =========
 
+5.0.3 (unreleased)
+------------------
+
+* Added `WebServiceClient.Builder.maxRetries(int)` to bound transport-failure
+  retries (default 1; set 0 to disable). See the README for retry semantics.
+
 5.0.2 (2025-12-08)
 ------------------
 

README.md

@@ -72,6 +72,50 @@ are not created for each request.
 See the [API documentation](https://maxmind.github.io/GeoIP2-java/) for
 more details.
 
+### Connection pooling and transport retries ###
+
+`WebServiceClient` is thread-safe and reuses a pooled `HttpClient` across
+requests. Idle connections in the pool can be silently closed by load
+balancers or other intermediaries. When the next request reuses one of these
+half-closed connections, the JDK reports the failure as a `Connection reset`,
+`Broken pipe`, or related transport `IOException`.
+
+To smooth over these intermittent transport failures, the SDK retries once
+by default. Any transport-level `IOException` raised by the underlying HTTP
+send is retried, with the following exclusions:
+
+* `HttpTimeoutException` — a request-phase timeout. Connect-phase timeouts
+  (`HttpConnectTimeoutException`) are also excluded because they extend
+  `HttpTimeoutException`. The SDK honors the timeouts you configure.
+* `InterruptedIOException` — the calling thread was interrupted; the SDK
+  honors the cancellation rather than override it.
+* Typically deterministic failures: `UnknownHostException`,
+  `ConnectException`, `SSLHandshakeException`, `SSLPeerUnverifiedException`.
+  Retrying these would just delay surfacing a config bug.
+* If the calling thread is already interrupted when the predicate runs, the
+  retry is short-circuited regardless of the exception type.
+
+HTTP 4xx and 5xx responses are not retried — they are returned as
+`HttpResponse` objects (not `IOException`s) and surfaced through the existing
+exception hierarchy. Web service requests are idempotent GETs, so retried
+requests are byte-identical to the original.
+
+You can change the retry budget via the builder:
+
+```java
+WebServiceClient client = new WebServiceClient.Builder(42, "license_key")
+    .maxRetries(2) // up to two retries (three total attempts)
+    .build();
+```
+
+Set `.maxRetries(0)` to disable the retry entirely. Negative values throw
+`IllegalArgumentException`.
+
+If you frequently see `Connection reset` errors, you can also reduce the
+JDK's keep-alive timeout via the system property
+`jdk.httpclient.keepalive.timeout` (in seconds) to evict pooled connections
+before any intermediary does so.
+
 ## Web Service Example ##
 
 ### Country Service ###