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 both InterruptedException rewrap paths. Updates README and CHANGELOG; opt out via .maxRetries(0).

Fixes STF-322. Parallel PR for geoip2-java uses a byte-identical predicate.

Test plan

• mvn checkstyle:check clean
• mvn verify — 235/235 pass (24 existing + 8 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 transport-failure retry mechanism to the WebServiceClient, defaulting to one retry for specific IOExceptions such as connection resets, broken pipes, and connect timeouts. The implementation includes a new maxRetries configuration in the WebServiceClient.Builder, updated documentation in the README and CHANGELOG, and comprehensive test coverage for various retry scenarios. Feedback was provided regarding a potential integer overflow in the sendWithRetry method; if maxRetries is set to Integer.MAX_VALUE, the loop condition fails and results in a NullPointerException because lastException remains null. A refactor was suggested to use a while loop to avoid this overflow and simplify the logic.

[gemini-code-assist]

The current implementation of sendWithRetry has a potential NullPointerException due to integer overflow and contains redundant logic.

If maxRetries is set to Integer.MAX_VALUE, the expression maxRetries + 1 overflows to Integer.MIN_VALUE. Consequently, the loop condition i < attempts (i.e., 0 < -2147483648) evaluates to false, the loop is skipped entirely, and the method proceeds to throw lastException;. Since lastException is initialized to null, a NullPointerException is thrown instead of the intended transport error.

Additionally, the lastException variable is redundant because the loop is designed to either return a successful response or throw the current exception e on the final attempt or upon encountering a non-retriable failure. Refactoring to a while loop avoids the overflow risk and simplifies the logic.

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