Enhance HttpHandler API to support separate connection and read timeouts

[cuioss-oliver]

Enhancement: Support Separate Connection and Read Timeouts in HttpHandler

This PR implements the enhancement requested in issue #86 to support separate connection and read timeouts in the HttpHandler API.

Changes Made

HttpHandler.java

• Removed the old requestTimeoutSeconds method completely (as per issue requirements - no backward compatibility needed)
• Added separate connectionTimeoutSeconds() and readTimeoutSeconds() methods to the builder
• Updated constructor to accept separate timeout parameters
• Updated HttpClient creation to use connection timeout via connectTimeout(Duration)
• Updated HttpRequest creation to use read timeout via timeout(Duration)
• Added validation for both timeout parameters with clear error messages
• Updated documentation and examples to demonstrate the new API

HttpHandlerTest.java

• Updated all test cases to use the new separate timeout API
• Added comprehensive tests for both connection and read timeout validation
• Updated test constants to reflect separate timeout values
• Enhanced asBuilder() tests to verify both timeouts are preserved

API Changes

Before:

HttpHandler handler = HttpHandler.builder()
    .uri("https://example.com/api")
    .requestTimeoutSeconds(10)  // Single timeout for everything
    .build();

After:

HttpHandler handler = HttpHandler.builder()
    .uri("https://example.com/api")
    .connectionTimeoutSeconds(5)   // Time to establish connection
    .readTimeoutSeconds(10)        // Time to read response
    .build();

Benefits

1. More precise timeout control: Applications can fine-tune connection vs read timeout behavior
2. Clearer API semantics: Method names match actual behavior
3. Better error handling: Can distinguish between connection failures and slow response reading
4. Industry standard: Aligns with how most HTTP client libraries handle timeouts

Implementation Details

• Connection timeout is applied to HttpClient.Builder.connectTimeout(Duration)
• Read timeout is applied to HttpRequest.Builder.timeout(Duration)
• Default values: 10 seconds for both connection and read timeouts
• Both timeouts must be positive integers
• The asBuilder() method correctly preserves both timeout values

Testing

• All existing tests updated to use new API
• New tests added for separate timeout validation
• Full test suite passes successfully
• No breaking changes to other components

Closes #86

[gemini-code-assist]

Summary of Changes

Hello @cuioss, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request refactors the HttpHandler API to offer more granular control over HTTP request timeouts by introducing separate connection and read timeout configurations. This change improves the precision of timeout handling, provides clearer API semantics, and enhances error handling by allowing applications to distinguish between connection establishment failures and slow response reading, bringing the API in line with industry standards.

Highlights

• API Enhancement: The HttpHandler API has been enhanced to provide separate control over connection and read timeouts, addressing issue #86. This replaces the single requestTimeoutSeconds with distinct connectionTimeoutSeconds and readTimeoutSeconds methods in the builder.
• Timeout Application: Connection timeout is now applied to HttpClient.Builder.connectTimeout(Duration), and read timeout is applied to HttpRequest.Builder.timeout(Duration), aligning with standard HTTP client practices.
• Default Values & Validation: Both connection and read timeouts now default to 10 seconds. New validation has been added to ensure both timeout parameters are positive integers, throwing IllegalArgumentException otherwise.
• Builder and Test Updates: The HttpHandlerBuilder and asBuilder() methods have been updated to correctly handle and preserve the new separate timeout parameters. All relevant unit tests in HttpHandlerTest.java have been updated and new tests added to cover the new timeout validation and behavior.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point in your pull request via creating an issue comment (i.e. comment on the pull request page) using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in issue comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist is currently in preview and may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments to provide feedback.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

The pull request introduces separate connection and read timeouts in the HttpHandler API. The changes include removing the old requestTimeoutSeconds method, adding separate connectionTimeoutSeconds() and readTimeoutSeconds() methods to the builder, updating the constructor and HttpClient/HttpRequest creation to use the new timeouts, and adding validation for the timeout parameters. The tests have been updated to use the new API and include comprehensive tests for timeout validation.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
100.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud