STF-322: Bounded transport-failure retry in WebServiceClient

[oschwald]

Summary

• Adds WebServiceClient.Builder.maxRetries(int) (defaults to 1) so a single stale-keep-alive Connection reset / Broken pipe / connect-failure is retried transparently.
• Predicate is narrow: retries HttpConnectTimeoutException, ConnectException, and SocketException matching Connection reset / Broken pipe (walks the cause chain, since the JDK wraps these in a generic IOException). Never retries request-phase HttpTimeoutException, 4xx, or 5xx.
• Restores the interrupt flag in the InterruptedException rewrap path. Updates README and CHANGELOG; opt out via .maxRetries(0).

Fixes STF-322. Parallel PR for minfraud-api-java uses a byte-identical predicate (maxmind/minfraud-api-java#619).

Test plan

• mvn checkstyle:check clean
• mvn verify -Dgpg.skip=true — 102/102 pass (28 existing + 9 new WebServiceClientTest cases)
• Reviewer sanity-checks the predicate ordering (HttpConnectTimeoutException MUST be checked before its parent HttpTimeoutException)
• Reviewer confirms README guidance points customers at jdk.httpclient.keepalive.timeout as the complementary workaround

🤖 Generated with Claude Code

[gemini-code-assist]

Code Review

This pull request introduces a configurable retry mechanism for transport-level failures in the WebServiceClient, defaulting to one retry for issues like connection resets or broken pipes. The implementation includes updates to the Builder for maxRetries configuration, detailed documentation in the README, and comprehensive test coverage for various failure scenarios. Feedback suggests refactoring the retry loop to prevent potential integer overflow and adopting case-insensitive string matching for exception messages to improve robustness across different environments.

[gemini-code-assist]

The current implementation of sendWithRetry is susceptible to an integer overflow if maxRetries is set to Integer.MAX_VALUE. In such a case, attempts would become Integer.MIN_VALUE, the loop condition i < attempts would be immediately false, and the method would throw a NullPointerException when reaching throw lastException because lastException remains null. Additionally, the lastException variable and the final throw statement are redundant as the loop is designed to either return a response or throw the last encountered exception. Refactoring the loop to check the retry count directly within the catch block improves robustness and clarity.

    private HttpResponse<InputStream> sendWithRetry(HttpRequest request)
        throws IOException, InterruptedException {
        for (int i = 0; ; i++) {
            try {
                return httpClient.send(request, HttpResponse.BodyHandlers.ofInputStream());
            } catch (IOException e) {
                if (i >= maxRetries || !isRetriableTransportFailure(e)) {
                    throw e;
                }
            }
        }
    }

[gemini-code-assist]

The message check for SocketException is case-sensitive. While "Connection reset" and "Broken pipe" are standard messages, they can vary in casing or include additional text depending on the operating system and JDK version (e.g., "connection reset by peer"). Using a case-insensitive check would make the retry logic more robust across different environments.

Suggested change

	&& (msg.contains("Connection reset") || msg.contains("Broken pipe"));
	&& (msg.toLowerCase(java.util.Locale.ROOT).contains("connection reset") || msg.toLowerCase(java.util.Locale.ROOT).contains("broken pipe"));