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