Merge branch 'a2aproject:main' into fix-local-handling-race-condition

ehsavoie · web-flow · commit 08986b322b49 · 2026-04-01T11:14:47.000+02:00
diff --git a/client/base/src/main/java/io/a2a/client/ClientBuilder.java b/client/base/src/main/java/io/a2a/client/ClientBuilder.java
@@ -328,15 +328,17 @@ private ClientTransport buildClientTransport() throws A2AClientException {
         return wrap(clientTransportProvider.create(clientTransportConfig, agentCard, agentInterface), clientTransportConfig);
     }
 
-    private Map<String, String> getServerPreferredTransports() throws A2AClientException {
-        Map<String, String> serverPreferredTransports = new LinkedHashMap<>();
-        if(agentCard.supportedInterfaces() == null || agentCard.supportedInterfaces().isEmpty()) {
+    private Map<String, AgentInterface> getServerInterfacesMap() throws A2AClientException {
+        List<AgentInterface> serverInterfaces = agentCard.supportedInterfaces();
+        if (serverInterfaces == null || serverInterfaces.isEmpty()) {
             throw new A2AClientException("No server interface available in the AgentCard");
         }
-        for (AgentInterface agentInterface : agentCard.supportedInterfaces()) {
-            serverPreferredTransports.putIfAbsent(agentInterface.protocolBinding(), agentInterface.url());
+        // If there are multiple interfaces with the same protocol binding, only the first is considered
+        Map<String, AgentInterface> serverInterfacesMap = new LinkedHashMap<>();
+        for (AgentInterface iface : serverInterfaces) {
+            serverInterfacesMap.putIfAbsent(iface.protocolBinding(), iface);
         }
-        return serverPreferredTransports;
+        return serverInterfacesMap;
     }
 
     private List<String> getClientPreferredTransports() {
@@ -351,40 +353,38 @@ private List<String> getClientPreferredTransports() {
         return supportedClientTransports;
     }
 
-    private AgentInterface findBestClientTransport() throws A2AClientException {
-        // Retrieve transport supported by the A2A server
-        Map<String, String> serverPreferredTransports = getServerPreferredTransports();
-
-        // Retrieve transport configured for this client (using withTransport methods)
+    // Package-private for testing
+    AgentInterface findBestClientTransport() throws A2AClientException {
+        Map<String, AgentInterface> serverInterfacesMap = getServerInterfacesMap();
         List<String> clientPreferredTransports = getClientPreferredTransports();
 
-        String transportProtocol = null;
-        String transportUrl = null;
+        AgentInterface matchedInterface = null;
         if (clientConfig.isUseClientPreference()) {
+            // Client preference: iterate client transports first, find first server match
             for (String clientPreferredTransport : clientPreferredTransports) {
-                if (serverPreferredTransports.containsKey(clientPreferredTransport)) {
-                    transportProtocol = clientPreferredTransport;
-                    transportUrl = serverPreferredTransports.get(transportProtocol);
+                if (serverInterfacesMap.containsKey(clientPreferredTransport)) {
+                    matchedInterface = serverInterfacesMap.get(clientPreferredTransport);
                     break;
                 }
             }
         } else {
-            for (Map.Entry<String, String> transport : serverPreferredTransports.entrySet()) {
-                if (clientPreferredTransports.contains(transport.getKey())) {
-                    transportProtocol = transport.getKey();
-                    transportUrl = transport.getValue();
+            // Server preference: iterate server interfaces first, find first client match
+            for (AgentInterface iface : serverInterfacesMap.values()) {
+                if (clientPreferredTransports.contains(iface.protocolBinding())) {
+                    matchedInterface = iface;
                     break;
                 }
             }
         }
-        if (transportProtocol == null || transportUrl == null) {
+
+        if (matchedInterface == null) {
             throw new A2AClientException("No compatible transport found");
         }
-        if (!transportProviderRegistry.containsKey(transportProtocol)) {
-            throw new A2AClientException("No client available for " + transportProtocol);
+        if (!transportProviderRegistry.containsKey(matchedInterface.protocolBinding())) {
+            throw new A2AClientException("No client available for " + matchedInterface.protocolBinding());
         }
 
-        return new AgentInterface(transportProtocol, transportUrl);
+        return matchedInterface;
     }
 
     /**
diff --git a/client/base/src/test/java/io/a2a/client/ClientBuilderTest.java b/client/base/src/test/java/io/a2a/client/ClientBuilderTest.java
@@ -1,6 +1,5 @@
 package io.a2a.client;
 
-
 import java.util.Collections;
 import java.util.List;
 
@@ -22,27 +21,38 @@
 
 public class ClientBuilderTest {
 
-    private AgentCard card = AgentCard.builder()
-            .name("Hello World Agent")
+    private static AgentCard buildCard(List<AgentInterface> interfaces) {
+        return AgentCard.builder()
+                .name("Hello World Agent")
                 .description("Just a hello world agent")
                 .version("1.0.0")
                 .documentationUrl("http://example.com/docs")
                 .capabilities(AgentCapabilities.builder()
                         .streaming(true)
                         .pushNotifications(true)
                         .build())
-            .defaultInputModes(Collections.singletonList("text"))
-            .defaultOutputModes(Collections.singletonList("text"))
-            .skills(Collections.singletonList(AgentSkill.builder()
-                                .id("hello_world")
-                                .name("Returns hello world")
-                                .description("just returns hello world")
-                                .tags(Collections.singletonList("hello world"))
-            .examples(List.of("hi", "hello world"))
-            .build()))
-            .supportedInterfaces(List.of(
-                    new AgentInterface(TransportProtocol.JSONRPC.asString(), "http://localhost:9999")))
-            .build();
+                .defaultInputModes(Collections.singletonList("text"))
+                .defaultOutputModes(Collections.singletonList("text"))
+                .skills(Collections.singletonList(AgentSkill.builder()
+                        .id("hello_world")
+                        .name("Returns hello world")
+                        .description("just returns hello world")
+                        .tags(Collections.singletonList("hello world"))
+                        .examples(List.of("hi", "hello world"))
+                        .build()))
+                .supportedInterfaces(interfaces)
+                .build();
+    }
+
+    private final AgentCard card = buildCard(List.of(
+            new AgentInterface(TransportProtocol.JSONRPC.asString(), "http://localhost:9999")));
+
+    private final AgentCard cardWithTenant = buildCard(List.of(
+            new AgentInterface(TransportProtocol.JSONRPC.asString(), "http://localhost:9999", "/default-tenant")));
+
+    private final AgentCard cardWithMultipleInterfaces = buildCard(List.of(
+            new AgentInterface(TransportProtocol.GRPC.asString(), "http://localhost:9998", "/grpc-tenant", "1.0"),
+            new AgentInterface(TransportProtocol.JSONRPC.asString(), "http://localhost:9999", "/jsonrpc-tenant", "1.0")));
 
     @Test
     public void shouldNotFindCompatibleTransport() throws A2AClientException {
@@ -91,4 +101,75 @@ public void shouldCreateClient_differentConfigurations() throws A2AClientExcepti
 
         Assertions.assertNotNull(client);
     }
+
+    @Test
+    public void shouldPreserveTenantFromAgentInterface() throws A2AClientException {
+        ClientBuilder builder = Client
+                .builder(cardWithTenant)
+                .withTransport(JSONRPCTransport.class, new JSONRPCTransportConfigBuilder());
+
+        AgentInterface selectedInterface = builder.findBestClientTransport();
+
+        Assertions.assertEquals("/default-tenant", selectedInterface.tenant());
+        Assertions.assertEquals("http://localhost:9999", selectedInterface.url());
+        Assertions.assertEquals(TransportProtocol.JSONRPC.asString(), selectedInterface.protocolBinding());
+    }
+
+    @Test
+    public void shouldPreserveProtocolVersionFromAgentInterface() throws A2AClientException {
+        ClientBuilder builder = Client
+                .builder(cardWithMultipleInterfaces)
+                .withTransport(JSONRPCTransport.class, new JSONRPCTransportConfigBuilder());
+
+        AgentInterface selectedInterface = builder.findBestClientTransport();
+
+        Assertions.assertEquals("/jsonrpc-tenant", selectedInterface.tenant());
+        Assertions.assertEquals("1.0", selectedInterface.protocolVersion());
+    }
+
+    @Test
+    public void shouldSelectCorrectInterfaceWithServerPreference() throws A2AClientException {
+        // Server preference (default): iterates server interfaces in order, picks first that client supports
+        // cardWithMultipleInterfaces has [GRPC, JSONRPC] - GRPC is first
+        // Client supports both GRPC and JSONRPC, so GRPC should be selected (server's first choice)
+        ClientBuilder builder = Client
+                .builder(cardWithMultipleInterfaces)
+                .withTransport(GrpcTransport.class, new GrpcTransportConfigBuilder().channelFactory(s -> null))
+                .withTransport(JSONRPCTransport.class, new JSONRPCTransportConfigBuilder());
+
+        AgentInterface selectedInterface = builder.findBestClientTransport();
+
+        Assertions.assertEquals(TransportProtocol.GRPC.asString(), selectedInterface.protocolBinding());
+        Assertions.assertEquals("http://localhost:9998", selectedInterface.url());
+        Assertions.assertEquals("/grpc-tenant", selectedInterface.tenant());
+    }
+
+    @Test
+    public void shouldSelectCorrectInterfaceWithClientPreference() throws A2AClientException {
+        // Client preference: iterates client transports in registration order, picks first that server supports
+        // Client registers [JSONRPC, GRPC] - JSONRPC is first
+        // Server supports both, so JSONRPC should be selected (client's first choice)
+        ClientBuilder builder = Client
+                .builder(cardWithMultipleInterfaces)
+                .clientConfig(new ClientConfig.Builder().setUseClientPreference(true).build())
+                .withTransport(JSONRPCTransport.class, new JSONRPCTransportConfigBuilder())
+                .withTransport(GrpcTransport.class, new GrpcTransportConfigBuilder().channelFactory(s -> null));
+
+        AgentInterface selectedInterface = builder.findBestClientTransport();
+
+        Assertions.assertEquals(TransportProtocol.JSONRPC.asString(), selectedInterface.protocolBinding());
+        Assertions.assertEquals("http://localhost:9999", selectedInterface.url());
+        Assertions.assertEquals("/jsonrpc-tenant", selectedInterface.tenant());
+    }
+
+    @Test
+    public void shouldPreserveEmptyTenant() throws A2AClientException {
+        ClientBuilder builder = Client
+                .builder(card)
+                .withTransport(JSONRPCTransport.class, new JSONRPCTransportConfigBuilder());
+
+        AgentInterface selectedInterface = builder.findBestClientTransport();
+
+        Assertions.assertEquals("", selectedInterface.tenant());
+    }
 }
diff --git a/spec/src/main/java/io/a2a/spec/DataPart.java b/spec/src/main/java/io/a2a/spec/DataPart.java
@@ -1,6 +1,10 @@
 package io.a2a.spec;
 
 
+import com.google.gson.Gson;
+import com.google.gson.GsonBuilder;
+import com.google.gson.JsonSyntaxException;
+import com.google.gson.ToNumberPolicy;
 import io.a2a.util.Assert;
 import java.util.Map;
 import org.jspecify.annotations.Nullable;
@@ -77,4 +81,59 @@ public DataPart (Object data, @Nullable Map<String, Object> metadata) {
     public DataPart(Object data) {
         this(data, null);
     }
+
+    /**
+     * Creates a DataPart by parsing a JSON string into its corresponding Java type.
+     * <p>
+     * The JSON string is parsed using Gson with {@code ToNumberPolicy.LONG_OR_DOUBLE},
+     * producing the following mappings:
+     * <ul>
+     *   <li>JSON objects → {@code Map<String, Object>}</li>
+     *   <li>JSON arrays → {@code List<Object>}</li>
+     *   <li>JSON strings → {@code String}</li>
+     *   <li>JSON integers → {@code Long}</li>
+     *   <li>JSON decimals → {@code Double}</li>
+     *   <li>JSON booleans → {@code Boolean}</li>
+     * </ul>
+     * <p>
+     * Example usage:
+     * <pre>{@code
+     * DataPart dataPart = DataPart.fromJson("""
+     *     {
+     *         "temperature": 22.5,
+     *         "humidity": 65
+     *     }""");
+     * }</pre>
+     *
+     * @param json the JSON string to parse (must not be null or the JSON literal "null")
+     * @return a new DataPart containing the parsed data
+     * @throws IllegalArgumentException if json is null, parses to null, or is not valid
+     */
+    public static DataPart fromJson(String json) {
+        return fromJson(json, null);
+    }
+
+    /**
+     * Creates a DataPart by parsing a JSON string into its corresponding Java type,
+     * with optional metadata.
+     *
+     * @param json the JSON string to parse (must not be null or the JSON literal "null")
+     * @param metadata additional metadata for the part
+     * @return a new DataPart containing the parsed data and metadata
+     * @throws IllegalArgumentException if json is null, parses to null, or is not valid
+     * @see #fromJson(String)
+     */
+    public static DataPart fromJson(String json, @Nullable Map<String, Object> metadata) {
+        Assert.checkNotNullParam("json", json);
+        try {
+            Object data = JSON_PARSER.fromJson(json, Object.class);
+            return new DataPart(data, metadata);
+        } catch (JsonSyntaxException e) {
+            throw new IllegalArgumentException("Invalid JSON: " + json, e);
+        }
+    }
+
+    private static final Gson JSON_PARSER = new GsonBuilder()
+            .setObjectToNumberStrategy(ToNumberPolicy.LONG_OR_DOUBLE)
+            .create();
 }
diff --git a/spec/src/test/java/io/a2a/spec/DataPartTest.java b/spec/src/test/java/io/a2a/spec/DataPartTest.java
@@ -0,0 +1,97 @@
+package io.a2a.spec;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertInstanceOf;
+import static org.junit.jupiter.api.Assertions.assertNull;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+
+import java.util.List;
+import java.util.Map;
+
+import org.junit.jupiter.api.Test;
+
+class DataPartTest {
+
+    @Test
+    void testFromJson_object() {
+        DataPart part = DataPart.fromJson("""
+                {"temperature": 22.5, "humidity": 65}""");
+
+        Map<String, Object> data = assertInstanceOf(Map.class, part.data());
+        assertEquals(22.5, data.get("temperature"));
+        assertEquals(65L, data.get("humidity"));
+        assertNull(part.metadata());
+    }
+
+    @Test
+    void testFromJson_array() {
+        DataPart part = DataPart.fromJson("""
+                ["a", "b", "c"]""");
+
+        List<Object> data = assertInstanceOf(List.class, part.data());
+        assertEquals(List.of("a", "b", "c"), data);
+    }
+
+    @Test
+    void testFromJson_string() {
+        DataPart part = DataPart.fromJson("\"hello\"");
+
+        assertEquals("hello", part.data());
+    }
+
+    @Test
+    void testFromJson_integerNumber() {
+        DataPart part = DataPart.fromJson("42");
+
+        assertEquals(42L, part.data());
+    }
+
+    @Test
+    void testFromJson_decimalNumber() {
+        DataPart part = DataPart.fromJson("3.14");
+
+        assertEquals(3.14, part.data());
+    }
+
+    @Test
+    void testFromJson_boolean() {
+        DataPart part = DataPart.fromJson("true");
+
+        assertEquals(true, part.data());
+    }
+
+    @Test
+    void testFromJson_withMetadata() {
+        Map<String, Object> metadata = Map.of("source", "sensor");
+        DataPart part = DataPart.fromJson("""
+                {"temperature": 22.5}""", metadata);
+
+        assertInstanceOf(Map.class, part.data());
+        assertEquals("sensor", part.metadata().get("source"));
+    }
+
+    @Test
+    void testFromJson_nestedObject() {
+        DataPart part = DataPart.fromJson("""
+                {"outer": {"inner": [1, 2, 3]}}""");
+
+        Map<String, Object> data = assertInstanceOf(Map.class, part.data());
+        Map<String, Object> outer = assertInstanceOf(Map.class, data.get("outer"));
+        assertEquals(List.of(1L, 2L, 3L), outer.get("inner"));
+    }
+
+    @Test
+    void testFromJson_nullJsonThrows() {
+        assertThrows(IllegalArgumentException.class, () -> DataPart.fromJson(null));
+    }
+
+    @Test
+    void testFromJson_nullLiteralThrows() {
+        assertThrows(IllegalArgumentException.class, () -> DataPart.fromJson("null"));
+    }
+
+    @Test
+    void testFromJson_invalidJsonThrows() {
+        assertThrows(IllegalArgumentException.class, () -> DataPart.fromJson("{invalid}"));
+    }
+}
