From 28feba617431852679c50ecdad2b882c62207522 Mon Sep 17 00:00:00 2001 From: Emmanuel Hugonnet Date: Fri, 20 Nov 2026 17:38:07 +0100 Subject: [PATCH] fix(client): require interceptor request payloads Provide a non-null request to client interceptors and reject null payloads at construction. For REST extended agent card calls, expose the tenant to interceptors and use the returned tenant when building the request URL. Add tests for tenant interception and null payload validation. Signed-off-by: Emmanuel Hugonnet --- .../transport/jsonrpc/JSONRPCTransport.java | 5 +- .../client/transport/rest/RestTransport.java | 18 ++++-- .../transport/rest/RestTransportTest.java | 64 +++++++++++++++++++ .../interceptors/ClientCallInterceptor.java | 6 +- .../spi/interceptors/PayloadAndHeaders.java | 16 +++-- .../interceptors/auth/AuthInterceptor.java | 6 +- .../interceptors/PayloadAndHeadersTest.java | 13 ++++ .../sdk/util/InterceptorPayloads.java | 32 ++++++++++ .../sdk/util/InterceptorPayloadsTest.java | 25 ++++++++ .../transport/rest/RestTransport_v0_3.java | 11 ++-- .../ClientCallInterceptor_v0_3.java | 2 +- .../interceptors/PayloadAndHeaders_v0_3.java | 16 +++-- .../auth/AuthInterceptor_v0_3.java | 2 +- docs/content/dev/client.md | 22 +++++++ 14 files changed, 210 insertions(+), 28 deletions(-) create mode 100644 client/transport/spi/src/test/java/org/a2aproject/sdk/client/transport/spi/interceptors/PayloadAndHeadersTest.java create mode 100644 common/src/main/java/org/a2aproject/sdk/util/InterceptorPayloads.java create mode 100644 common/src/test/java/org/a2aproject/sdk/util/InterceptorPayloadsTest.java diff --git a/client/transport/jsonrpc/src/main/java/org/a2aproject/sdk/client/transport/jsonrpc/JSONRPCTransport.java b/client/transport/jsonrpc/src/main/java/org/a2aproject/sdk/client/transport/jsonrpc/JSONRPCTransport.java index 334e01878..328d6ba67 100644 --- a/client/transport/jsonrpc/src/main/java/org/a2aproject/sdk/client/transport/jsonrpc/JSONRPCTransport.java +++ b/client/transport/jsonrpc/src/main/java/org/a2aproject/sdk/client/transport/jsonrpc/JSONRPCTransport.java @@ -68,6 +68,7 @@ import org.a2aproject.sdk.spec.TaskPushNotificationConfig; import org.a2aproject.sdk.spec.TaskQueryParams; import org.a2aproject.sdk.spec.util.Utils; +import org.a2aproject.sdk.util.InterceptorPayloads; import org.jspecify.annotations.Nullable; public class JSONRPCTransport implements ClientTransport { @@ -328,7 +329,7 @@ public void close() { // no-op } - private PayloadAndHeaders applyInterceptors(String methodName, @Nullable Object payload, + private PayloadAndHeaders applyInterceptors(String methodName, Object payload, @Nullable AgentCard agentCard, @Nullable ClientCallContext clientCallContext) { PayloadAndHeaders payloadAndHeaders = new PayloadAndHeaders(payload, getHttpHeaders(clientCallContext)); if (interceptors != null && ! interceptors.isEmpty()) { @@ -362,7 +363,7 @@ private A2AHttpClient.PostBuilder createPostBuilder( .addHeader("Content-Type", "application/json") .addHeader(A2AHeaders.A2A_VERSION, AgentInterface.CURRENT_PROTOCOL_VERSION) .followRedirects(followRedirects) - .body(JSONRPCUtils.toJsonRPCRequest(requestId, method, (MessageOrBuilder) payloadAndHeaders.getPayload())); + .body(JSONRPCUtils.toJsonRPCRequest(requestId, method, InterceptorPayloads.cast(payloadAndHeaders.getPayload(), MessageOrBuilder.class))); if (payloadAndHeaders.getHeaders() != null) { for (Map.Entry entry : payloadAndHeaders.getHeaders().entrySet()) { diff --git a/client/transport/rest/src/main/java/org/a2aproject/sdk/client/transport/rest/RestTransport.java b/client/transport/rest/src/main/java/org/a2aproject/sdk/client/transport/rest/RestTransport.java index d51549c70..7fc90083b 100644 --- a/client/transport/rest/src/main/java/org/a2aproject/sdk/client/transport/rest/RestTransport.java +++ b/client/transport/rest/src/main/java/org/a2aproject/sdk/client/transport/rest/RestTransport.java @@ -62,6 +62,7 @@ import org.a2aproject.sdk.spec.TaskPushNotificationConfig; import org.a2aproject.sdk.spec.TaskQueryParams; import org.a2aproject.sdk.spec.util.Utils; +import org.a2aproject.sdk.util.InterceptorPayloads; import org.jspecify.annotations.Nullable; public class RestTransport implements ClientTransport { @@ -441,8 +442,15 @@ public void subscribeToTask(TaskIdParams request, Consumer e @Override public AgentCard getExtendedAgentCard(GetExtendedAgentCardParams params, @Nullable ClientCallContext context) throws A2AClientException { try { - PayloadAndHeaders payloadAndHeaders = applyInterceptors(GET_EXTENDED_AGENT_CARD_METHOD, null, agentCard, context); - String url = Utils.buildBaseUrl(agentInterface, params.tenant()) + "/extendedAgentCard"; + org.a2aproject.sdk.grpc.GetExtendedAgentCardRequest.Builder builder = org.a2aproject.sdk.grpc.GetExtendedAgentCardRequest.newBuilder(); + if (params.tenant() != null) { + builder.setTenant(params.tenant()); + } + PayloadAndHeaders payloadAndHeaders = applyInterceptors(GET_EXTENDED_AGENT_CARD_METHOD, builder, agentCard, context); + org.a2aproject.sdk.grpc.GetExtendedAgentCardRequestOrBuilder interceptedRequest = + InterceptorPayloads.cast(payloadAndHeaders.getPayload(), + org.a2aproject.sdk.grpc.GetExtendedAgentCardRequestOrBuilder.class); + String url = Utils.buildBaseUrl(agentInterface, interceptedRequest.getTenant()) + "/extendedAgentCard"; A2AHttpClient.GetBuilder getBuilder = httpClient.createGet().url(url); addStandardHeaders(getBuilder, payloadAndHeaders); A2AHttpResponse response = getBuilder.get(); @@ -463,7 +471,7 @@ public void close() { // no-op } - private PayloadAndHeaders applyInterceptors(String methodName, @Nullable MessageOrBuilder payload, + private PayloadAndHeaders applyInterceptors(String methodName, MessageOrBuilder payload, AgentCard agentCard, @Nullable ClientCallContext clientCallContext) { PayloadAndHeaders payloadAndHeaders = new PayloadAndHeaders(payload, getHttpHeaders(clientCallContext)); if (interceptors != null && !interceptors.isEmpty()) { @@ -476,7 +484,7 @@ private PayloadAndHeaders applyInterceptors(String methodName, @Nullable Message } private String sendPostRequest(String url, PayloadAndHeaders payloadAndHeaders) throws IOException, InterruptedException, JsonProcessingException { - MessageOrBuilder payload = (MessageOrBuilder) payloadAndHeaders.getPayload(); + MessageOrBuilder payload = InterceptorPayloads.cast(payloadAndHeaders.getPayload(), MessageOrBuilder.class); String body = payload != null ? ProtoJsonUtils.toJson(JsonFormat.printer(), payload) : ""; if (LOGGER.isLoggable(Level.FINE)) { LOGGER.fine(body); @@ -495,7 +503,7 @@ private String sendPostRequest(String url, PayloadAndHeaders payloadAndHeaders) private A2AHttpClient.PostBuilder createPostBuilder( String url, PayloadAndHeaders payloadAndHeaders, boolean followRedirects) throws JsonProcessingException, InvalidProtocolBufferException { - String body = ProtoJsonUtils.toJson(JsonFormat.printer(), (MessageOrBuilder) payloadAndHeaders.getPayload()); + String body = ProtoJsonUtils.toJson(JsonFormat.printer(), InterceptorPayloads.cast(payloadAndHeaders.getPayload(), MessageOrBuilder.class)); if (LOGGER.isLoggable(Level.FINE)) { LOGGER.fine(body); } diff --git a/client/transport/rest/src/test/java/org/a2aproject/sdk/client/transport/rest/RestTransportTest.java b/client/transport/rest/src/test/java/org/a2aproject/sdk/client/transport/rest/RestTransportTest.java index 74311ee9b..2a21dd9a5 100644 --- a/client/transport/rest/src/test/java/org/a2aproject/sdk/client/transport/rest/RestTransportTest.java +++ b/client/transport/rest/src/test/java/org/a2aproject/sdk/client/transport/rest/RestTransportTest.java @@ -19,6 +19,7 @@ import static org.junit.jupiter.api.Assertions.assertInstanceOf; import static org.junit.jupiter.api.Assertions.assertNotNull; import static org.junit.jupiter.api.Assertions.assertNull; +import static org.junit.jupiter.api.Assertions.assertThrows; import static org.junit.jupiter.api.Assertions.assertTrue; import static org.mockserver.model.HttpRequest.request; import static org.mockserver.model.HttpResponse.response; @@ -52,6 +53,7 @@ import org.a2aproject.sdk.spec.FilePart; import org.a2aproject.sdk.spec.FileWithBytes; import org.a2aproject.sdk.spec.FileWithUri; +import org.a2aproject.sdk.spec.GetExtendedAgentCardParams; import org.a2aproject.sdk.spec.GetTaskPushNotificationConfigParams; import org.a2aproject.sdk.spec.ListTaskPushNotificationConfigsParams; import org.a2aproject.sdk.spec.ListTaskPushNotificationConfigsResult; @@ -124,6 +126,68 @@ public void configBuilderEnablesRedirectFollowing() { public RestTransportTest() { } + @Test + public void testExtendedAgentCardUsesInterceptedTenant() throws Exception { + ClientCallInterceptor interceptor = new ClientCallInterceptor() { + @Override + public PayloadAndHeaders intercept(String methodName, Object payload, + java.util.Map headers, AgentCard agentCard, + ClientCallContext clientCallContext) { + org.a2aproject.sdk.grpc.GetExtendedAgentCardRequest.Builder request = + (org.a2aproject.sdk.grpc.GetExtendedAgentCardRequest.Builder) payload; + assertEquals("original", request.getTenant()); + return new PayloadAndHeaders(request.setTenant("intercepted").build(), headers); + } + }; + server.when(request().withMethod("GET").withPath("/intercepted/extendedAgentCard")) + .respond(response().withStatusCode(200).withBody(new Gson().toJson(CARD))); + + AgentInterface agentInterface = new AgentInterface("HTTP+JSON", "http://localhost:4001"); + RestTransport client = new RestTransport(null, CARD, agentInterface, List.of(interceptor)); + assertEquals(CARD.name(), client.getExtendedAgentCard(new GetExtendedAgentCardParams("original"), null).name()); + } + + @Test + public void testExtendedAgentCardInterceptorReceivesAbsentTenant() throws Exception { + AtomicReference capturedTenant = new AtomicReference<>(); + ClientCallInterceptor interceptor = new ClientCallInterceptor() { + @Override + public PayloadAndHeaders intercept(String methodName, Object payload, + java.util.Map headers, AgentCard agentCard, + ClientCallContext clientCallContext) { + org.a2aproject.sdk.grpc.GetExtendedAgentCardRequestOrBuilder request = + (org.a2aproject.sdk.grpc.GetExtendedAgentCardRequestOrBuilder) payload; + capturedTenant.set(request.getTenant()); + return new PayloadAndHeaders(payload, headers); + } + }; + server.when(request().withMethod("GET").withPath("/extendedAgentCard")) + .respond(response().withStatusCode(200).withBody(new Gson().toJson(CARD))); + + AgentInterface agentInterface = new AgentInterface("HTTP+JSON", "http://localhost:4001"); + RestTransport client = new RestTransport(null, CARD, agentInterface, List.of(interceptor)); + client.getExtendedAgentCard(new GetExtendedAgentCardParams(null), null); + assertEquals("", capturedTenant.get()); + } + + @Test + public void testExtendedAgentCardRejectsUnrelatedInterceptorPayload() { + ClientCallInterceptor interceptor = new ClientCallInterceptor() { + @Override + public PayloadAndHeaders intercept(String methodName, Object payload, + java.util.Map headers, AgentCard agentCard, ClientCallContext context) { + return new PayloadAndHeaders("unexpected", headers); + } + }; + AgentInterface agentInterface = new AgentInterface("HTTP+JSON", "http://localhost:4001"); + RestTransport client = new RestTransport(null, CARD, agentInterface, List.of(interceptor)); + + IllegalArgumentException exception = assertThrows(IllegalArgumentException.class, + () -> client.getExtendedAgentCard(new GetExtendedAgentCardParams(null), null)); + assertEquals("Interceptor payload must be org.a2aproject.sdk.grpc.GetExtendedAgentCardRequestOrBuilder; got java.lang.String", + exception.getMessage()); + } + /** * Test of sendMessage method, of class JSONRestTransport. */ diff --git a/client/transport/spi/src/main/java/org/a2aproject/sdk/client/transport/spi/interceptors/ClientCallInterceptor.java b/client/transport/spi/src/main/java/org/a2aproject/sdk/client/transport/spi/interceptors/ClientCallInterceptor.java index 7d9e08fb9..d0a04d352 100644 --- a/client/transport/spi/src/main/java/org/a2aproject/sdk/client/transport/spi/interceptors/ClientCallInterceptor.java +++ b/client/transport/spi/src/main/java/org/a2aproject/sdk/client/transport/spi/interceptors/ClientCallInterceptor.java @@ -16,12 +16,12 @@ public abstract class ClientCallInterceptor { * Intercept a client call before the request is sent. * * @param methodName the name of the protocol method (e.g., 'message/send') - * @param payload the request payload + * @param payload the non-null request payload * @param headers the headers to use * @param agentCard the agent card (may be {@code null}) * @param clientCallContext the {@code ClientCallContext} for this call (may be {@code null}) - * @return the potentially modified payload and headers + * @return the potentially modified payload and headers; the payload must not be null */ - public abstract PayloadAndHeaders intercept(String methodName, @Nullable Object payload, Map headers, + public abstract PayloadAndHeaders intercept(String methodName, Object payload, Map headers, @Nullable AgentCard agentCard, @Nullable ClientCallContext clientCallContext); } diff --git a/client/transport/spi/src/main/java/org/a2aproject/sdk/client/transport/spi/interceptors/PayloadAndHeaders.java b/client/transport/spi/src/main/java/org/a2aproject/sdk/client/transport/spi/interceptors/PayloadAndHeaders.java index 03dc61126..601a60b94 100644 --- a/client/transport/spi/src/main/java/org/a2aproject/sdk/client/transport/spi/interceptors/PayloadAndHeaders.java +++ b/client/transport/spi/src/main/java/org/a2aproject/sdk/client/transport/spi/interceptors/PayloadAndHeaders.java @@ -4,19 +4,27 @@ import java.util.HashMap; import java.util.Map; +import org.a2aproject.sdk.util.Assert; import org.jspecify.annotations.Nullable; public class PayloadAndHeaders { - private final @Nullable Object payload; + private final Object payload; private final Map headers; - public PayloadAndHeaders(@Nullable Object payload, @Nullable Map headers) { - this.payload = payload; + /** + * Creates an interceptor result. + * + * @param payload the non-null request payload + * @param headers the request headers, or null for an empty map + * @throws IllegalArgumentException if payload is null + */ + public PayloadAndHeaders(Object payload, @Nullable Map headers) { + this.payload = Assert.checkNotNullParam("payload", payload); this.headers = headers == null ? Collections.emptyMap() : new HashMap<>(headers); } - public @Nullable Object getPayload() { + public Object getPayload() { return payload; } diff --git a/client/transport/spi/src/main/java/org/a2aproject/sdk/client/transport/spi/interceptors/auth/AuthInterceptor.java b/client/transport/spi/src/main/java/org/a2aproject/sdk/client/transport/spi/interceptors/auth/AuthInterceptor.java index 2bb1272a2..e87f5d3ca 100644 --- a/client/transport/spi/src/main/java/org/a2aproject/sdk/client/transport/spi/interceptors/auth/AuthInterceptor.java +++ b/client/transport/spi/src/main/java/org/a2aproject/sdk/client/transport/spi/interceptors/auth/AuthInterceptor.java @@ -51,7 +51,7 @@ public AuthInterceptor(final CredentialService credentialService) { } @Override - public PayloadAndHeaders intercept(String methodName, @Nullable Object payload, Map headers, + public PayloadAndHeaders intercept(String methodName, Object payload, Map headers, @Nullable AgentCard agentCard, @Nullable ClientCallContext clientCallContext) { Map updatedHeaders = new HashMap<>(headers == null ? new HashMap<>() : headers); if (agentCard == null || agentCard.securityRequirements()== null || agentCard.securitySchemes() == null) { @@ -70,10 +70,10 @@ public PayloadAndHeaders intercept(String methodName, @Nullable Object payload, } if (securityScheme instanceof HTTPAuthSecurityScheme httpAuthSecurityScheme) { String scheme = httpAuthSecurityScheme.scheme().toLowerCase(Locale.ROOT); - if (scheme.equals(BEARER_SCHEME)) { + if (BEARER_SCHEME.equals(scheme)) { updatedHeaders.put(AUTHORIZATION, getBearerValue(credential)); return new PayloadAndHeaders(payload, updatedHeaders); - } else if (scheme.equals(BASIC_SCHEME)) { + } else if (BASIC_SCHEME.equals(scheme)) { updatedHeaders.put(AUTHORIZATION, getBasicValue(credential)); return new PayloadAndHeaders(payload, updatedHeaders); } diff --git a/client/transport/spi/src/test/java/org/a2aproject/sdk/client/transport/spi/interceptors/PayloadAndHeadersTest.java b/client/transport/spi/src/test/java/org/a2aproject/sdk/client/transport/spi/interceptors/PayloadAndHeadersTest.java new file mode 100644 index 000000000..6fb1d9d17 --- /dev/null +++ b/client/transport/spi/src/test/java/org/a2aproject/sdk/client/transport/spi/interceptors/PayloadAndHeadersTest.java @@ -0,0 +1,13 @@ +package org.a2aproject.sdk.client.transport.spi.interceptors; + +import static org.junit.jupiter.api.Assertions.assertThrows; + +import org.junit.jupiter.api.Test; + +class PayloadAndHeadersTest { + + @Test + void rejectsNullPayload() { + assertThrows(IllegalArgumentException.class, () -> new PayloadAndHeaders(null, null)); + } +} diff --git a/common/src/main/java/org/a2aproject/sdk/util/InterceptorPayloads.java b/common/src/main/java/org/a2aproject/sdk/util/InterceptorPayloads.java new file mode 100644 index 000000000..99b9d408c --- /dev/null +++ b/common/src/main/java/org/a2aproject/sdk/util/InterceptorPayloads.java @@ -0,0 +1,32 @@ +package org.a2aproject.sdk.util; + +import org.jspecify.annotations.Nullable; + +/** Type checks for payloads returned by client interceptors. */ +public final class InterceptorPayloads { + + private InterceptorPayloads() { + } + + /** + * Casts a non-null interceptor payload. + * + * @param payload the interceptor payload + * @param expectedType the expected payload type + * @param the expected payload type + * @return the cast payload + * @throws IllegalArgumentException if the payload has an unexpected type + */ + public static T cast(Object payload, Class expectedType) { + return Assert.checkNotNullParam("payload", castNullable(payload, expectedType)); + } + + /** Casts a payload while preserving null for transports that allow it. */ + public static @Nullable T castNullable(@Nullable Object payload, Class expectedType) { + if (payload != null && !expectedType.isInstance(payload)) { + throw new IllegalArgumentException("Interceptor payload must be " + expectedType.getName() + + "; got " + payload.getClass().getName()); + } + return expectedType.cast(payload); + } +} diff --git a/common/src/test/java/org/a2aproject/sdk/util/InterceptorPayloadsTest.java b/common/src/test/java/org/a2aproject/sdk/util/InterceptorPayloadsTest.java new file mode 100644 index 000000000..eb7a8f464 --- /dev/null +++ b/common/src/test/java/org/a2aproject/sdk/util/InterceptorPayloadsTest.java @@ -0,0 +1,25 @@ +package org.a2aproject.sdk.util; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertNull; +import static org.junit.jupiter.api.Assertions.assertSame; +import static org.junit.jupiter.api.Assertions.assertThrows; + +import org.junit.jupiter.api.Test; + +class InterceptorPayloadsTest { + + @Test + void castsCompatiblePayloadsAndPreservesNull() { + String payload = "request"; + assertSame(payload, InterceptorPayloads.cast(payload, CharSequence.class)); + assertNull(InterceptorPayloads.castNullable(null, CharSequence.class)); + } + + @Test + void describesUnexpectedPayloadType() { + IllegalArgumentException exception = assertThrows(IllegalArgumentException.class, + () -> InterceptorPayloads.cast(42, CharSequence.class)); + assertEquals("Interceptor payload must be java.lang.CharSequence; got java.lang.Integer", exception.getMessage()); + } +} diff --git a/compat-0.3/client/transport/rest/src/main/java/org/a2aproject/sdk/compat03/client/transport/rest/RestTransport_v0_3.java b/compat-0.3/client/transport/rest/src/main/java/org/a2aproject/sdk/compat03/client/transport/rest/RestTransport_v0_3.java index fc5e051d0..481c41d88 100644 --- a/compat-0.3/client/transport/rest/src/main/java/org/a2aproject/sdk/compat03/client/transport/rest/RestTransport_v0_3.java +++ b/compat-0.3/client/transport/rest/src/main/java/org/a2aproject/sdk/compat03/client/transport/rest/RestTransport_v0_3.java @@ -9,7 +9,6 @@ import org.a2aproject.sdk.client.http.A2AHttpClient; import org.a2aproject.sdk.client.http.A2AHttpClientFactory; import org.a2aproject.sdk.client.http.A2AHttpResponse; -import org.a2aproject.sdk.client.http.ServerSentEvent; import org.a2aproject.sdk.compat03.client.http.A2ACardResolver_v0_3; import org.a2aproject.sdk.compat03.client.transport.rest.sse.RestSSEEventListener_v0_3; import org.a2aproject.sdk.compat03.client.transport.spi.ClientTransport_v0_3; @@ -57,6 +56,7 @@ import java.util.concurrent.atomic.AtomicReference; import java.util.function.Consumer; import org.a2aproject.sdk.grpc.utils.ProtoJsonUtils; +import org.a2aproject.sdk.util.InterceptorPayloads; import org.jspecify.annotations.Nullable; public class RestTransport_v0_3 implements ClientTransport_v0_3 { @@ -339,7 +339,8 @@ public AgentCard_v0_3 getAgentCard(@Nullable ClientCallContext_v0_3 context) thr if (!needsExtendedCard) { return agentCard; } - PayloadAndHeaders_v0_3 payloadAndHeaders = applyInterceptors(GetAuthenticatedExtendedCardRequest_v0_3.METHOD, null, + org.a2aproject.sdk.compat03.grpc.GetAgentCardRequestOrBuilder builder = org.a2aproject.sdk.compat03.grpc.GetAgentCardRequest.newBuilder(); + PayloadAndHeaders_v0_3 payloadAndHeaders = applyInterceptors(GetAuthenticatedExtendedCardRequest_v0_3.METHOD, builder, agentCard, context); String url = agentUrl + String.format("/v1/card"); A2AHttpClient.GetBuilder getBuilder = httpClient.createGet().url(url); @@ -368,7 +369,7 @@ public void close() { // no-op } - private PayloadAndHeaders_v0_3 applyInterceptors(String methodName, @Nullable MessageOrBuilder payload, + private PayloadAndHeaders_v0_3 applyInterceptors(String methodName, MessageOrBuilder payload, AgentCard_v0_3 agentCard, @Nullable ClientCallContext_v0_3 clientCallContext) { PayloadAndHeaders_v0_3 payloadAndHeaders = new PayloadAndHeaders_v0_3(payload, getHttpHeaders(clientCallContext)); if (interceptors != null && !interceptors.isEmpty()) { @@ -381,7 +382,7 @@ private PayloadAndHeaders_v0_3 applyInterceptors(String methodName, @Nullable Me } private String sendPostRequest(String url, PayloadAndHeaders_v0_3 payloadAndHeaders) throws IOException, InterruptedException, JsonProcessingException_v0_3 { - MessageOrBuilder payload = (MessageOrBuilder) payloadAndHeaders.getPayload(); + MessageOrBuilder payload = InterceptorPayloads.castNullable(payloadAndHeaders.getPayload(), MessageOrBuilder.class); String body = payload != null ? ProtoJsonUtils.toJson(JsonFormat.printer(), payload) : ""; if (LOGGER.isLoggable(Level.FINE)) { LOGGER.fine(body); @@ -398,7 +399,7 @@ private String sendPostRequest(String url, PayloadAndHeaders_v0_3 payloadAndHead } private A2AHttpClient.PostBuilder createPostBuilder(String url, PayloadAndHeaders_v0_3 payloadAndHeaders) throws JsonProcessingException_v0_3, InvalidProtocolBufferException { - String body = ProtoJsonUtils_v0_3.toJson(JsonFormat.printer(), (MessageOrBuilder) payloadAndHeaders.getPayload()); + String body = ProtoJsonUtils_v0_3.toJson(JsonFormat.printer(), InterceptorPayloads.castNullable(payloadAndHeaders.getPayload(), MessageOrBuilder.class)); if (LOGGER.isLoggable(Level.FINE)) { LOGGER.fine(body); } diff --git a/compat-0.3/client/transport/spi/src/main/java/org/a2aproject/sdk/compat03/client/transport/spi/interceptors/ClientCallInterceptor_v0_3.java b/compat-0.3/client/transport/spi/src/main/java/org/a2aproject/sdk/compat03/client/transport/spi/interceptors/ClientCallInterceptor_v0_3.java index fc0e76584..22440b975 100644 --- a/compat-0.3/client/transport/spi/src/main/java/org/a2aproject/sdk/compat03/client/transport/spi/interceptors/ClientCallInterceptor_v0_3.java +++ b/compat-0.3/client/transport/spi/src/main/java/org/a2aproject/sdk/compat03/client/transport/spi/interceptors/ClientCallInterceptor_v0_3.java @@ -22,6 +22,6 @@ public abstract class ClientCallInterceptor_v0_3 { * @param clientCallContext the {@code ClientCallContext} for this call (may be {@code null}) * @return the potentially modified payload and headers */ - public abstract PayloadAndHeaders_v0_3 intercept(String methodName, @Nullable Object payload, Map headers, + public abstract PayloadAndHeaders_v0_3 intercept(String methodName, Object payload, Map headers, AgentCard_v0_3 agentCard, @Nullable ClientCallContext_v0_3 clientCallContext); } diff --git a/compat-0.3/client/transport/spi/src/main/java/org/a2aproject/sdk/compat03/client/transport/spi/interceptors/PayloadAndHeaders_v0_3.java b/compat-0.3/client/transport/spi/src/main/java/org/a2aproject/sdk/compat03/client/transport/spi/interceptors/PayloadAndHeaders_v0_3.java index bc08d174c..483296980 100644 --- a/compat-0.3/client/transport/spi/src/main/java/org/a2aproject/sdk/compat03/client/transport/spi/interceptors/PayloadAndHeaders_v0_3.java +++ b/compat-0.3/client/transport/spi/src/main/java/org/a2aproject/sdk/compat03/client/transport/spi/interceptors/PayloadAndHeaders_v0_3.java @@ -3,19 +3,27 @@ import java.util.Collections; import java.util.HashMap; import java.util.Map; +import org.a2aproject.sdk.util.Assert; import org.jspecify.annotations.Nullable; public class PayloadAndHeaders_v0_3 { - private final @Nullable Object payload; + private final Object payload; private final Map headers; - public PayloadAndHeaders_v0_3(@Nullable Object payload, @Nullable Map headers) { - this.payload = payload; + /** + * Creates an interceptor result. + * + * @param payload the non-null request payload + * @param headers the request headers, or null for an empty map + * @throws IllegalArgumentException if payload is null + */ + public PayloadAndHeaders_v0_3(Object payload, @Nullable Map headers) { + this.payload = Assert.checkNotNullParam("payload", payload); this.headers = headers == null ? Collections.emptyMap() : new HashMap<>(headers); } - public @Nullable Object getPayload() { + public Object getPayload() { return payload; } diff --git a/compat-0.3/client/transport/spi/src/main/java/org/a2aproject/sdk/compat03/client/transport/spi/interceptors/auth/AuthInterceptor_v0_3.java b/compat-0.3/client/transport/spi/src/main/java/org/a2aproject/sdk/compat03/client/transport/spi/interceptors/auth/AuthInterceptor_v0_3.java index 5ff604a18..b5d064c8d 100644 --- a/compat-0.3/client/transport/spi/src/main/java/org/a2aproject/sdk/compat03/client/transport/spi/interceptors/auth/AuthInterceptor_v0_3.java +++ b/compat-0.3/client/transport/spi/src/main/java/org/a2aproject/sdk/compat03/client/transport/spi/interceptors/auth/AuthInterceptor_v0_3.java @@ -51,7 +51,7 @@ public AuthInterceptor_v0_3(final CredentialService_v0_3 credentialService) { } @Override - public PayloadAndHeaders_v0_3 intercept(String methodName, @Nullable Object payload, Map headers, + public PayloadAndHeaders_v0_3 intercept(String methodName, Object payload, Map headers, AgentCard_v0_3 agentCard, @Nullable ClientCallContext_v0_3 clientCallContext) { Map updatedHeaders = new HashMap<>(headers == null ? new HashMap<>() : headers); if (agentCard == null || agentCard.security() == null || agentCard.securitySchemes() == null) { diff --git a/docs/content/dev/client.md b/docs/content/dev/client.md index 92faff1e2..2fc7c8c9c 100644 --- a/docs/content/dev/client.md +++ b/docs/content/dev/client.md @@ -135,6 +135,28 @@ client.deleteTaskPushNotificationConfigurations( ## Transport Configuration +### Client Interceptor Payloads + +Client call interceptors receive a non-null request payload and must return a +`PayloadAndHeaders` with a non-null payload. The `PayloadAndHeaders` constructor +throws `IllegalArgumentException` if the payload is null. Headers may still be +null, in which case they are treated as an empty map. + +**Migration:** Existing interceptors that construct `PayloadAndHeaders` with a +null payload must pass through the received payload or provide a non-null +replacement of the appropriate request type. For an interceptor that only +changes headers, return the original payload: + +```java +return new PayloadAndHeaders(payload, updatedHeaders); +``` + +For REST extended-agent-card calls, interceptors previously received a null +payload. They now receive a `GetExtendedAgentCardRequest.Builder` containing +the tenant, or an empty tenant string when none was supplied. The REST URL uses +the tenant from the request returned by the interceptor, including when it +returns a replacement `GetExtendedAgentCardRequest`. + ### JSON-RPC with a Custom HTTP Client ```java