feat: Provide a new http-client layer to create new HTTP client implementation / extensions (vertx)

Author: brasseld

README.md

@@ -349,13 +349,13 @@ Different transport protocols can be configured with specific settings using spe
 
 ##### JSON-RPC Transport Configuration
 
-For the JSON-RPC transport, to use the default `JdkA2AHttpClient`, provide a `JSONRPCTransportConfig` created with its default constructor.
+For the JSON-RPC transport, to use the default `JdkHttpClient`, provide a `JSONRPCTransportConfig` created with its default constructor.
 
 To use a custom HTTP client implementation, simply create a `JSONRPCTransportConfig` as follows:
 
 ```java
-// Create a custom HTTP client
-A2AHttpClient customHttpClient = ...
+// Create a custom HTTP client builder
+HttpClientBuilder httpClientBuilder = ...
 
 // Configure the client settings
 ClientConfig clientConfig = new ClientConfig.Builder()
@@ -365,7 +365,7 @@ ClientConfig clientConfig = new ClientConfig.Builder()
 Client client = Client
         .builder(agentCard)
         .clientConfig(clientConfig)
-        .withTransport(JSONRPCTransport.class, new JSONRPCTransportConfig(customHttpClient))
+        .withTransport(JSONRPCTransport.class, new JSONRPCTransportConfig(httpClientBuilder))
         .build();
 ```
 
@@ -396,13 +396,13 @@ Client client = Client
 
 ##### HTTP+JSON/REST Transport Configuration
 
-For the HTTP+JSON/REST transport, if you'd like to use the default `JdkA2AHttpClient`, provide a `RestTransportConfig` created with its default constructor.
+For the HTTP+JSON/REST transport, if you'd like to use the default `JdkHttpClient`, provide a `RestTransportConfig` created with its default constructor.
 
 To use a custom HTTP client implementation, simply create a `RestTransportConfig` as follows:
 
 ```java
 // Create a custom HTTP client
-A2AHttpClient customHttpClient = ...
+HttpClientBuilder httpClientBuilder = ...
 
 // Configure the client settings
 ClientConfig clientConfig = new ClientConfig.Builder()
@@ -412,7 +412,7 @@ ClientConfig clientConfig = new ClientConfig.Builder()
 Client client = Client
         .builder(agentCard)
         .clientConfig(clientConfig)
-        .withTransport(RestTransport.class, new RestTransportConfig(customHttpClient))
+        .withTransport(RestTransport.class, new RestTransportConfig(httpClientBuilder))
         .build();
 ```
 

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

@@ -3,11 +3,9 @@
 import java.util.Collections;
 import java.util.List;
 import java.util.Map;
-import java.util.UUID;
 
 import io.a2a.client.http.A2ACardResolver;
-import io.a2a.client.http.A2AHttpClient;
-import io.a2a.client.http.JdkA2AHttpClient;
+import io.a2a.client.http.HttpClient;
 import io.a2a.spec.A2AClientError;
 import io.a2a.spec.A2AClientJSONError;
 import io.a2a.spec.AgentCard;
@@ -139,51 +137,37 @@ private static Message toMessage(List<Part<?>> parts, Message.Role role, String
      * @throws A2AClientJSONError f the response body cannot be decoded as JSON or validated against the AgentCard schema
      */
     public static AgentCard getAgentCard(String agentUrl) throws A2AClientError, A2AClientJSONError {
-        return getAgentCard(new JdkA2AHttpClient(), agentUrl);
-    }
-
-    /**
-     * Get the agent card for an A2A agent.
-     *
-     * @param httpClient the http client to use
-     * @param agentUrl the base URL for the agent whose agent card we want to retrieve
-     * @return the agent card
-     * @throws A2AClientError If an HTTP error occurs fetching the card
-     * @throws A2AClientJSONError f the response body cannot be decoded as JSON or validated against the AgentCard schema
-     */
-    public static AgentCard getAgentCard(A2AHttpClient httpClient, String agentUrl) throws A2AClientError, A2AClientJSONError  {
-        return getAgentCard(httpClient, agentUrl, null, null);
+        return getAgentCard(HttpClient.createHttpClient(agentUrl), null, null);
     }
 
     /**
      * Get the agent card for an A2A agent.
      *
      * @param agentUrl the base URL for the agent whose agent card we want to retrieve
      * @param relativeCardPath optional path to the agent card endpoint relative to the base
-     *                         agent URL, defaults to ".well-known/agent-card.json"
+     *                         agent URL, defaults to "/.well-known/agent-card.json"
      * @param authHeaders the HTTP authentication headers to use
      * @return the agent card
      * @throws A2AClientError If an HTTP error occurs fetching the card
      * @throws A2AClientJSONError f the response body cannot be decoded as JSON or validated against the AgentCard schema
      */
     public static AgentCard getAgentCard(String agentUrl, String relativeCardPath, Map<String, String> authHeaders) throws A2AClientError, A2AClientJSONError {
-        return getAgentCard(new JdkA2AHttpClient(), agentUrl, relativeCardPath, authHeaders);
+        return getAgentCard(HttpClient.createHttpClient(agentUrl), relativeCardPath, authHeaders);
     }
 
     /**
      * Get the agent card for an A2A agent.
      *
      * @param httpClient the http client to use
-     * @param agentUrl the base URL for the agent whose agent card we want to retrieve
      * @param relativeCardPath optional path to the agent card endpoint relative to the base
-     *                         agent URL, defaults to ".well-known/agent-card.json"
+     *                         agent URL, defaults to "/.well-known/agent-card.json"
      * @param authHeaders the HTTP authentication headers to use
      * @return the agent card
      * @throws A2AClientError If an HTTP error occurs fetching the card
      * @throws A2AClientJSONError f the response body cannot be decoded as JSON or validated against the AgentCard schema
      */
-    public static AgentCard getAgentCard(A2AHttpClient httpClient, String agentUrl, String relativeCardPath, Map<String, String> authHeaders) throws A2AClientError, A2AClientJSONError  {
-        A2ACardResolver resolver = new A2ACardResolver(httpClient, agentUrl, relativeCardPath, authHeaders);
+    public static AgentCard getAgentCard(HttpClient httpClient, String relativeCardPath, Map<String, String> authHeaders) throws A2AClientError, A2AClientJSONError  {
+        A2ACardResolver resolver = new A2ACardResolver(httpClient, relativeCardPath, authHeaders);
         return resolver.getAgentCard();
     }
 }

client/base/src/test/java/io/a2a/client/ClientBuilderTest.java

@@ -1,7 +1,8 @@
 package io.a2a.client;
 
 import io.a2a.client.config.ClientConfig;
-import io.a2a.client.http.JdkA2AHttpClient;
+import io.a2a.client.http.HttpClientBuilder;
+import io.a2a.client.http.jdk.JdkHttpClientBuilder;
 import io.a2a.client.transport.grpc.GrpcTransport;
 import io.a2a.client.transport.grpc.GrpcTransportConfigBuilder;
 import io.a2a.client.transport.jsonrpc.JSONRPCTransport;
@@ -71,13 +72,40 @@ public void shouldNotFindConfigurationTransport() throws A2AClientException {
     }
 
     @Test
-    public void shouldCreateJSONRPCClient() throws A2AClientException {
+    public void shouldNotCreateJSONRPCClient_nullHttpClientFactory() throws A2AClientException {
+        Assertions.assertThrows(IllegalArgumentException.class,
+                () -> {
+                    Client
+                            .builder(card)
+                            .clientConfig(new ClientConfig.Builder().setUseClientPreference(true).build())
+                            .withTransport(JSONRPCTransport.class, new JSONRPCTransportConfigBuilder()
+                                    .addInterceptor(null)
+                                    .httpClientBuilder(null))
+                            .build();
+                });
+    }
+
+    @Test
+    public void shouldCreateJSONRPCClient_defaultHttpClientFactory() throws A2AClientException {
+        Client client = Client
+                .builder(card)
+                .clientConfig(new ClientConfig.Builder().setUseClientPreference(true).build())
+                .withTransport(JSONRPCTransport.class, new JSONRPCTransportConfigBuilder()
+                        .addInterceptor(null)
+                        .httpClientBuilder(HttpClientBuilder.DEFAULT_FACTORY))
+                .build();
+
+        Assertions.assertNotNull(client);
+    }
+
+    @Test
+    public void shouldCreateJSONRPCClient_withHttpClientFactory() throws A2AClientException {
         Client client = Client
                 .builder(card)
                 .clientConfig(new ClientConfig.Builder().setUseClientPreference(true).build())
                 .withTransport(JSONRPCTransport.class, new JSONRPCTransportConfigBuilder()
                         .addInterceptor(null)
-                        .httpClient(null))
+                        .httpClientBuilder(new JdkHttpClientBuilder()))
                 .build();
 
         Assertions.assertNotNull(client);
@@ -88,7 +116,7 @@ public void shouldCreateClient_differentConfigurations() throws A2AClientExcepti
         Client client = Client
                 .builder(card)
                 .withTransport(JSONRPCTransport.class, new JSONRPCTransportConfigBuilder())
-                .withTransport(JSONRPCTransport.class, new JSONRPCTransportConfig(new JdkA2AHttpClient()))
+                .withTransport(JSONRPCTransport.class, new JSONRPCTransportConfig())
                 .build();
 
         Assertions.assertNotNull(client);

client/transport/grpc/src/main/java/io/a2a/client/transport/grpc/GrpcTransport.java

@@ -11,8 +11,8 @@
 import java.util.function.Consumer;
 import java.util.stream.Collectors;
 
+import io.a2a.client.transport.spi.AbstractClientTransport;
 import io.a2a.client.transport.spi.interceptors.ClientCallContext;
-import io.a2a.client.transport.spi.ClientTransport;
 import io.a2a.client.transport.spi.interceptors.ClientCallInterceptor;
 import io.a2a.client.transport.spi.interceptors.PayloadAndHeaders;
 import io.a2a.client.transport.spi.interceptors.auth.AuthInterceptor;
@@ -50,7 +50,7 @@
 import io.grpc.stub.MetadataUtils;
 import io.grpc.stub.StreamObserver;
 
-public class GrpcTransport implements ClientTransport {
+public class GrpcTransport extends AbstractClientTransport {
 
     private static final Metadata.Key<String> AUTHORIZATION_METADATA_KEY = Metadata.Key.of(
             AuthInterceptor.AUTHORIZATION,
@@ -60,19 +60,18 @@ public class GrpcTransport implements ClientTransport {
             Metadata.ASCII_STRING_MARSHALLER);
     private final A2AServiceBlockingV2Stub blockingStub;
     private final A2AServiceStub asyncStub;
-    private final List<ClientCallInterceptor> interceptors;
     private AgentCard agentCard;
 
     public GrpcTransport(Channel channel, AgentCard agentCard) {
         this(channel, agentCard, null);
     }
 
     public GrpcTransport(Channel channel, AgentCard agentCard, List<ClientCallInterceptor> interceptors) {
+        super(interceptors);
         checkNotNullParam("channel", channel);
         this.asyncStub = A2AServiceGrpc.newStub(channel);
         this.blockingStub = A2AServiceGrpc.newBlockingV2Stub(channel);
         this.agentCard = agentCard;
-        this.interceptors = interceptors;
     }
 
     @Override
@@ -365,17 +364,4 @@ private String getTaskPushNotificationConfigName(String taskId, String pushNotif
         return name.toString();
     }
 
-    private PayloadAndHeaders applyInterceptors(String methodName, Object payload,
-                                                AgentCard agentCard, ClientCallContext clientCallContext) {
-        PayloadAndHeaders payloadAndHeaders = new PayloadAndHeaders(payload,
-                clientCallContext != null ? clientCallContext.getHeaders() : null);
-        if (interceptors != null && ! interceptors.isEmpty()) {
-            for (ClientCallInterceptor interceptor : interceptors) {
-                payloadAndHeaders = interceptor.intercept(methodName, payloadAndHeaders.getPayload(),
-                        payloadAndHeaders.getHeaders(), agentCard, clientCallContext);
-            }
-        }
-        return payloadAndHeaders;
-    }
-
 }