feat: Provide a new http-client layer to create new HTTP client imple… #347

brasseld · 2025-10-13T13:54:52Z

…entation to the transport layer (jsonrpc / rest+json)

The JDK-based implementation is kept as the reference implementation and a new extra module has been created to also provide a Vertx-based implementation which may be more suitable in the future.

Also, because of the non-blocking nature of Vertx, the current vertx implementation is not optimal (yet), and so, not suitable for production. Some additional work will be needed in the future to make it fully functional. What's needed:

http-client layer fully async (based on jdk Future ?)
build an asynchronous version of the Client (but still provide a sync version of it, as it is done for MCP Java SDK)

Description

Thank you for opening a Pull Request!
Before submitting your PR, there are a few things you can do to make sure it goes smoothly:

Follow the CONTRIBUTING Guide.
Make your Pull Request title in the https://www.conventionalcommits.org/ specification.
- Important Prefixes for release-please:
  - fix: which represents bug fixes, and correlates to a SemVer patch.
  - feat: represents a new feature, and correlates to a SemVer minor.
  - feat!:, or fix!:, refactor!:, etc., which represent a breaking change (indicated by the !) and will result in a SemVer major.
Ensure the tests pass
Appropriate READMEs were updated (if necessary)

gemini-code-assist · 2025-10-13T13:55:47Z

Summary of Changes

Hello @brasseld, 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 significantly refactors the HTTP client infrastructure within the SDK by introducing a new, extensible abstraction layer. This change decouples the client logic from specific HTTP client implementations, providing a default JDK-based client and a new optional Vertx-based client. It also centralizes the management of HTTP client instances on the server-side and enhances the handling of Server-Sent Events, making the SDK more adaptable and robust for various application environments.

Highlights

New HTTP Client Abstraction Layer: Introduced new HttpClient and HttpClientBuilder interfaces to abstract the underlying HTTP client implementation, allowing for greater flexibility and extensibility.
Default JDK HTTP Client Implementation: The existing JDK-based HTTP client functionality has been refactored to conform to the new HttpClient interface, serving as the default implementation.
Vertx HTTP Client Module: Added a new extras/http-client-vertx module, providing an alternative HttpClient implementation based on Vertx, which can be beneficial for Quarkus-based applications.
Centralized HTTP Client Management: A new HttpClientManager component has been introduced on the server-side to cache and manage HttpClient instances efficiently, improving resource utilization.
Enhanced Server-Sent Events (SSE) Handling: Improved SSE processing with dedicated Event, DataEvent, and CommentEvent classes, along with updated SSEHandler implementations for both JDK and Vertx clients.
Transport Layer Integration: Both JSON-RPC and REST transport layers have been updated to utilize the new HttpClient interfaces, ensuring consistent HTTP request handling across the SDK.

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 by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

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 pull request 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 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. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

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.

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

This pull request introduces a new abstraction layer for HTTP clients, allowing for different implementations like the newly added Vert.x-based client alongside the existing JDK one. The refactoring is extensive and touches many parts of the client and transport layers. My review focuses on ensuring the new abstraction is used correctly and the new implementations are robust. I've found a critical issue in the JSON-RPC transport related to agent card resolution, and a few medium-severity issues in the new Vert.x and JDK HTTP client implementations concerning SSE parsing and exception handling.

client/transport/jsonrpc/src/main/java/io/a2a/client/transport/jsonrpc/JSONRPCTransport.java

extras/http-client-vertx/src/main/java/io/a2a/client/http/vertx/VertxHttpClient.java

extras/http-client-vertx/src/main/java/io/a2a/client/http/vertx/sse/SSEHandler.java

http-client/src/main/java/io/a2a/client/http/jdk/JdkHttpClient.java

brasseld · 2025-10-14T05:43:06Z

/gemini review

gemini-code-assist

Code Review

This pull request introduces a significant and valuable refactoring by creating a new http-client layer, making the HTTP client implementation pluggable. This is a great architectural improvement that will enhance modularity and testability. The introduction of a Vert.x-based implementation as an alternative to the default JDK one is a good example of this new flexibility. My review focuses on ensuring the new abstraction is used correctly and identifying potential issues in the new implementations. I've found a critical issue in A2ACardResolver's usage of the new API, a bug in the new Vert.x SSE handler, and some minor areas for code cleanup. Overall, this is a solid contribution.

http-client/src/main/java/io/a2a/client/http/A2ACardResolver.java

extras/http-client-vertx/src/main/java/io/a2a/client/http/vertx/sse/SSEHandler.java

client/transport/jsonrpc/src/main/java/io/a2a/client/transport/jsonrpc/JSONRPCTransport.java

gemini-code-assist · 2025-10-14T05:45:34Z

.../a2a/extras/pushnotificationconfigstore/database/jpa/JpaPushNotificationConfigStoreTest.java

-        when(mockHttpClient.createPost()).thenReturn(mockPostBuilder);
-        when(mockPostBuilder.url(any(String.class))).thenReturn(mockPostBuilder);
+        when(mockHttpClient.post(any())).thenReturn(mockPostBuilder);
+//        when(mockPostBuilder.url(any(String.class))).thenReturn(mockPostBuilder);


This line of commented-out code should be removed. It seems to be a leftover from a previous implementation before the refactoring. Keeping commented-out code can reduce readability and lead to confusion.

brasseld · 2025-10-14T07:13:47Z

/gemini review

gemini-code-assist

Code Review

This pull request introduces a significant and well-structured refactoring to create an abstraction layer for HTTP clients, allowing for multiple implementations like the default JDK-based one and a new Vert.x-based one. The changes are extensive but follow a clear pattern, improving modularity and extensibility. I've identified a critical issue in the new Vert.x SSE handler that needs to be addressed, along with a couple of medium-severity suggestions for code improvement and consistency. Overall, this is a great enhancement to the SDK.

extras/http-client-vertx/src/main/java/io/a2a/client/http/vertx/sse/SSEHandler.java

client/transport/jsonrpc/src/main/java/io/a2a/client/transport/jsonrpc/JSONRPCTransport.java

brasseld · 2025-10-14T07:46:20Z

/gemini review

gemini-code-assist

Code Review

This pull request introduces a significant and well-designed refactoring of the HTTP client layer. The new HttpClient abstraction, along with the HttpClientBuilder, provides a clean and extensible way to support different HTTP client implementations, as demonstrated by the new Vert.x client module. The introduction of AbstractClientTransport to centralize interceptor logic and HttpClientManager for efficient client reuse are also excellent improvements.

However, I've found a critical issue in both JSONRPCTransport and RestTransport where the agentPath is incorrectly used instead of the full agentUrl when resolving the agent card. This will cause getAgentCard() to fail. I've left specific comments with suggestions on how to fix this.

Overall, this is a great contribution that significantly improves the architecture of the client. Once the identified issue is resolved, this will be ready to merge.

gemini-code-assist · 2025-10-14T07:49:26Z

client/transport/jsonrpc/src/main/java/io/a2a/client/transport/jsonrpc/JSONRPCTransport.java

        try {
            if (agentCard == null) {
-                resolver = new A2ACardResolver(httpClient, agentUrl, null, getHttpHeaders(context));
+                A2ACardResolver resolver = new A2ACardResolver(httpClient, agentPath, null, getHttpHeaders(context));


A2ACardResolver is being initialized with agentPath, but it requires the full base agentUrl to correctly resolve the agent card's location. This will cause requests for the agent card to fail.

To fix this, you should store the original agentUrl as a field in the JSONRPCTransport constructor and use that field here.

Suggested change

A2ACardResolver resolver = new A2ACardResolver(httpClient, agentPath, null, getHttpHeaders(context));

A2ACardResolver resolver = new A2ACardResolver(httpClient, agentUrl, null, getHttpHeaders(context));

gemini-code-assist · 2025-10-14T07:49:26Z

client/transport/rest/src/main/java/io/a2a/client/transport/rest/RestTransport.java

        try {
            if (agentCard == null) {
-                resolver = new A2ACardResolver(httpClient, agentUrl, null, getHttpHeaders(context));
+                resolver = new A2ACardResolver(httpClient, agentPath, null, getHttpHeaders(context));


A2ACardResolver is being initialized with agentPath, but it requires the full base agentUrl to correctly resolve the agent card's location. This will cause requests for the agent card to fail.

To fix this, you should store the original agentUrl as a field in the RestTransport constructor and use that field here.

Suggested change

resolver = new A2ACardResolver(httpClient, agentPath, null, getHttpHeaders(context));

resolver = new A2ACardResolver(httpClient, agentUrl, null, getHttpHeaders(context));

brasseld · 2025-10-14T09:35:31Z

/gemini review

gemini-code-assist

Code Review

This pull request introduces a significant and valuable refactoring by abstracting the HTTP client layer. This improves modularity and allows for different client implementations like the new Vert.x-based one. The introduction of AbstractClientTransport to share interceptor logic is also a great improvement for code reuse.

My review focuses on a few areas to further enhance robustness and performance. I've pointed out a fragile URL parsing implementation in the new JDK client and a potential runtime issue with handling response bodies in streaming scenarios. I've also suggested making a server-side component fully non-blocking to improve scalability. Finally, there's a small suggestion to reduce code duplication.

Overall, this is a solid architectural improvement.

extras/http-client-vertx/src/main/java/io/a2a/client/http/vertx/VertxHttpClient.java

http-client/src/main/java/io/a2a/client/http/jdk/JdkHttpClient.java

client/transport/jsonrpc/src/main/java/io/a2a/client/transport/jsonrpc/JSONRPCTransport.java

brasseld · 2025-10-14T09:54:28Z

/gemini review

gemini-code-assist

Code Review

This pull request introduces a significant and valuable refactoring by creating a new http-client abstraction layer. This change greatly improves modularity, allowing for different HTTP client implementations like the newly added Vert.x-based client. The introduction of AbstractClientTransport to centralize interceptor logic and HttpClientManager for efficient client reuse are excellent design choices. While the overall direction is very positive, I've identified a few areas for improvement related to asynchronous design consistency and potential resource management issues that would further strengthen this new architecture.

client/transport/rest/src/main/java/io/a2a/client/transport/rest/sse/RestSSEEventListener.java

http-client/src/main/java/io/a2a/client/http/HttpResponse.java

client/base/src/main/java/io/a2a/A2A.java

client/transport/jsonrpc/src/main/java/io/a2a/client/transport/jsonrpc/JSONRPCTransport.java

client/transport/rest/src/main/java/io/a2a/client/transport/rest/RestTransport.java

brasseld · 2025-10-14T11:36:37Z

/gemini review

gemini-code-assist

Code Review

This pull request introduces a significant and well-executed refactoring to provide a new HTTP client abstraction layer. This is a great step towards making the transport layer more extensible. The introduction of HttpClient and HttpClientBuilder interfaces, along with the default JDK implementation and a new Vert.x implementation, is well-designed. The refactoring of existing code to adopt this new layer is thorough. My review has identified a critical compilation issue due to missing imports, a missing nullability annotation that could affect code safety, and a minor naming inconsistency. Addressing these points will further improve the quality of this contribution.

client/transport/jsonrpc/src/main/java/io/a2a/client/transport/jsonrpc/JSONRPCTransport.java

client/transport/rest/src/main/java/io/a2a/client/transport/rest/RestTransportProvider.java

…mentation / extensions (vertx)

ehsavoie · 2025-10-14T19:09:55Z

I'm trying to add support for SSE in vertx-web vert-x3/vertx-web#2794 that I will backport to vertx 4 once I can get it merged. It should be more appropriate to handle this. WDYT ?

brasseld · 2025-10-14T20:26:42Z

I'm trying to add support for SSE in vertx-web vert-x3/vertx-web#2794 that I will backport to vertx 4 once I can get it merged. It should be more appropriate to handle this. WDYT ?

Good one @ehsavoie , definitely something which was missing in vertx-web !

My only (small) concern is that it will force us to use vertx-web, this PR was only relying on vertx-core.
Not sure if that's a big deal, but still worth to raise it!

brasseld · 2025-10-14T20:33:33Z

I've anticipated a bit what could come after this PR regarding the Async Client.
I created a draft PR here #349 which is based on this PR.

gemini-code-assist bot reviewed Oct 13, 2025

View reviewed changes

brasseld force-pushed the vertx_http_client branch from e1232f2 to f6d7f34 Compare October 14, 2025 05:42

gemini-code-assist bot reviewed Oct 14, 2025

View reviewed changes

brasseld force-pushed the vertx_http_client branch from f6d7f34 to 26001ef Compare October 14, 2025 07:13

gemini-code-assist bot reviewed Oct 14, 2025

View reviewed changes

brasseld force-pushed the vertx_http_client branch from 26001ef to f7fa2bf Compare October 14, 2025 07:45

gemini-code-assist bot reviewed Oct 14, 2025

View reviewed changes

brasseld force-pushed the vertx_http_client branch from f7fa2bf to b877ee2 Compare October 14, 2025 09:35

gemini-code-assist bot reviewed Oct 14, 2025

View reviewed changes

brasseld force-pushed the vertx_http_client branch from b877ee2 to d0b7c29 Compare October 14, 2025 09:54

gemini-code-assist bot reviewed Oct 14, 2025

View reviewed changes

brasseld force-pushed the vertx_http_client branch from d0b7c29 to d5e4ff5 Compare October 14, 2025 11:36

gemini-code-assist bot reviewed Oct 14, 2025

View reviewed changes

client/transport/jsonrpc/src/main/java/io/a2a/client/transport/jsonrpc/JSONRPCTransport.java Outdated Show resolved Hide resolved

client/transport/rest/src/main/java/io/a2a/client/transport/rest/RestTransportProvider.java Outdated Show resolved Hide resolved

feat: Provide a new http-client layer to create new HTTP client imple…

20392a0

…mentation / extensions (vertx)

brasseld force-pushed the vertx_http_client branch from d5e4ff5 to 20392a0 Compare October 14, 2025 11:45

	A2ACardResolver resolver = new A2ACardResolver(httpClient, agentPath, null, getHttpHeaders(context));
	A2ACardResolver resolver = new A2ACardResolver(httpClient, agentUrl, null, getHttpHeaders(context));

	resolver = new A2ACardResolver(httpClient, agentPath, null, getHttpHeaders(context));
	resolver = new A2ACardResolver(httpClient, agentUrl, null, getHttpHeaders(context));

feat: Provide a new http-client layer to create new HTTP client imple… #347

Are you sure you want to change the base?

feat: Provide a new http-client layer to create new HTTP client imple… #347

Uh oh!

Conversation

brasseld commented Oct 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Uh oh!

gemini-code-assist bot commented Oct 13, 2025

Summary of Changes

Highlights

Footnotes

Uh oh!

gemini-code-assist bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

brasseld commented Oct 14, 2025

Uh oh!

gemini-code-assist bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

Uh oh!

Uh oh!

gemini-code-assist bot Oct 14, 2025

Choose a reason for hiding this comment

Uh oh!

brasseld commented Oct 14, 2025

Uh oh!

gemini-code-assist bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

Uh oh!

Uh oh!

brasseld commented Oct 14, 2025

Uh oh!

gemini-code-assist bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

gemini-code-assist bot Oct 14, 2025

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist bot Oct 14, 2025

Choose a reason for hiding this comment

Uh oh!

brasseld commented Oct 14, 2025

Uh oh!

gemini-code-assist bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

brasseld commented Oct 14, 2025

Uh oh!

gemini-code-assist bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

brasseld commented Oct 14, 2025

Uh oh!

gemini-code-assist bot left a comment

Choose a reason for hiding this comment

brasseld commented Oct 13, 2025 •

edited

Loading