Skip to content

Commit 0b52bf2

Browse files
authored
feat(multitenancy): return 404 for unknown tenant on public agent card (a2aproject#1112)
- Add TenantNotFoundException; JSONRPCHandler and RestHandler throw/return 404 when AgentCardRouter is set but tenant not found - Single-tenant servers (no router) ignore the tenant segment and serve the default card - CdiAgentCardRouter.resolvePublicCard now returns null for unknown/blank tenants instead of the default card - Add Utils.buildTenantCardPath helper; restrict fallback retry in A2ACardResolver to 404 only - Update all tests to expect 404 for unknown tenants Fixes: a2aproject#1108 Signed-off-by: Emmanuel Hugonnet <ehugonne@redhat.com>
1 parent c440b86 commit 0b52bf2

16 files changed

Lines changed: 269 additions & 86 deletions

File tree

‎extras/multitenancy/src/main/java/org/a2aproject/sdk/extras/multitenancy/CdiAgentCardRouter.java‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -25,8 +25,9 @@
2525
* qualifier must NOT be used on tenant-specific public cards because it would cause CDI
2626
* ambiguity on injection points requesting the default public card.
2727
* <p>
28-
* Falls back to the default (non-{@code @Tenant}) card when the tenant is {@code null},
29-
* blank, or does not match any registered tenant.
28+
* Returns the default public card from {@link #resolvePublicCard} when the tenant is
29+
* {@code null} or blank. Returns {@code null} when a non-blank tenant does not match
30+
* any registered tenant — the caller treats that as a 404.
3031
*/
3132
@ApplicationScoped
3233
public class CdiAgentCardRouter implements AgentCardRouter {
@@ -74,6 +75,6 @@ void init() {
7475
return handle.get();
7576
}
7677
}
77-
return defaultPublicCard;
78+
return null;
7879
}
7980
}

‎extras/multitenancy/src/test/java/org/a2aproject/sdk/extras/multitenancy/it/MultiTenantJSONRPCTest.java‎

Lines changed: 3 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -122,13 +122,10 @@ public void getPublicAgentCardWithBetaTenant() {
122122
}
123123

124124
@Test
125-
public void getPublicAgentCardWithUnknownTenantFallsBackToDefault() {
126-
String response = RestAssured.given()
125+
public void unknownTenantReturns404() {
126+
RestAssured.given()
127127
.when().get("/.well-known/unknown/agent-card.json")
128-
.then().statusCode(200)
129-
.extract().asString();
130-
JsonPath json = JsonPath.from(response);
131-
assertEquals("Multi-Tenant Test Agent", json.getString("name"));
128+
.then().statusCode(404);
132129
}
133130

134131
@Test

‎extras/multitenancy/src/test/java/org/a2aproject/sdk/extras/multitenancy/it/MultiTenantRESTTest.java‎

Lines changed: 3 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -137,13 +137,10 @@ public void getPublicAgentCardWithBetaTenant() {
137137
}
138138

139139
@Test
140-
public void getPublicAgentCardWithUnknownTenantFallsBackToDefault() {
141-
String response = RestAssured.given()
140+
public void unknownTenantReturns404() {
141+
RestAssured.given()
142142
.when().get("/.well-known/unknown/agent-card.json")
143-
.then().statusCode(200)
144-
.extract().asString();
145-
JsonPath json = JsonPath.from(response);
146-
assertEquals("Multi-Tenant Test Agent", json.getString("name"));
143+
.then().statusCode(404);
147144
}
148145

149146
@Test

‎http-client/src/main/java/org/a2aproject/sdk/client/http/A2ACardResolver.java‎

Lines changed: 35 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -94,30 +94,9 @@ private A2ACardResolver(A2AHttpClient httpClient, String baseUrl, @Nullable Stri
9494
// Strip any well-known suffix from baseUrl so that a full card URL like
9595
// https://host/.well-known/agent-card.json doesn't produce a malformed path.
9696
String cleanBase = Utils.stripWellKnownSuffix(baseUrl);
97-
String resolvedCardUrl;
98-
@Nullable String resolvedFallbackUrl;
99-
if (agentCardPath != null && !agentCardPath.isEmpty()) {
100-
// Custom path: tenant goes as path prefix (explicit override); no fallback.
101-
String baseUrlWithTenant = Utils.buildBaseUrl(cleanBase, tenant);
102-
Utils.validateAbsoluteUrl(baseUrlWithTenant);
103-
resolvedCardUrl = Utils.buildCardUrl(baseUrlWithTenant, agentCardPath);
104-
resolvedFallbackUrl = null;
105-
} else {
106-
// Standard well-known path: optionally embed tenant inside the path.
107-
if (tenant != null && !tenant.isBlank()) {
108-
// {base}/.well-known/{tenant}/agent-card.json
109-
Utils.validateTenant(tenant);
110-
Utils.validateAbsoluteUrl(cleanBase);
111-
resolvedCardUrl = Utils.buildCardUrl(cleanBase, "/.well-known/" + Utils.normalizeTenant(tenant) + "/agent-card.json");
112-
} else {
113-
// {base}/.well-known/agent-card.json
114-
Utils.validateAbsoluteUrl(cleanBase);
115-
resolvedCardUrl = Utils.buildCardUrl(cleanBase, Utils.DEFAULT_AGENT_CARD_PATH);
116-
}
117-
resolvedFallbackUrl = isSameUrl(resolvedCardUrl, baseUrl) ? null : cleanBase;
118-
}
119-
this.cardUrl = resolvedCardUrl;
120-
this.fallbackUrl = resolvedFallbackUrl;
97+
ResolvedUrls resolved = resolveUrls(cleanBase, baseUrl, tenant, agentCardPath);
98+
this.cardUrl = resolved.cardUrl();
99+
this.fallbackUrl = resolved.fallbackUrl();
121100
} catch (URISyntaxException e) {
122101
throw new A2AClientError("Invalid agent URL", e);
123102
}
@@ -244,8 +223,8 @@ public A2ACardResolver build() throws A2AClientError {
244223
* <p>Fetches from the custom {@code agentCardPath} when one was supplied, otherwise fetches
245224
* from the standard {@code /.well-known/agent-card.json} (or tenant-specific variant) endpoint.
246225
* When no custom path was provided and the computed card URL differs from the originally
247-
* supplied base URL, a 404 on the primary URL triggers a single retry against the
248-
* original base URL before propagating the error.
226+
* supplied base URL, a 404 response from the primary URL triggers a single retry against
227+
* the original base URL before propagating the error.
249228
*
250229
* @return the agent card
251230
* @throws A2AClientHTTPError If the server returns a non-2xx response (carries status, body, and headers)
@@ -271,9 +250,37 @@ public AgentCard getAgentCard() throws A2AClientError, A2AClientJSONError {
271250
}
272251
}
273252

253+
private static ResolvedUrls resolveUrls(String cleanBase, String originalBase, @Nullable String tenant, @Nullable String agentCardPath) throws URISyntaxException {
254+
if (agentCardPath != null && !agentCardPath.isBlank()) {
255+
// Custom path: tenant goes as path prefix (explicit override); no fallback.
256+
String baseUrlWithTenant = Utils.buildBaseUrl(cleanBase, tenant);
257+
Utils.validateAbsoluteUrl(baseUrlWithTenant);
258+
return new ResolvedUrls(Utils.buildCardUrl(baseUrlWithTenant, agentCardPath), null);
259+
}
260+
// Standard well-known path: optionally embed tenant inside the path.
261+
String cardUrl;
262+
if (tenant != null && !tenant.isBlank()) {
263+
// {base}/.well-known/{tenant}/agent-card.json
264+
Utils.validateTenant(tenant);
265+
Utils.validateAbsoluteUrl(cleanBase);
266+
cardUrl = Utils.buildCardUrl(cleanBase, Utils.buildTenantCardPath(tenant));
267+
} else {
268+
// {base}/.well-known/agent-card.json
269+
Utils.validateAbsoluteUrl(cleanBase);
270+
cardUrl = Utils.buildCardUrl(cleanBase, Utils.DEFAULT_AGENT_CARD_PATH);
271+
}
272+
String fallbackUrl = isSameUrl(cardUrl, originalBase) ? null : cleanBase;
273+
return new ResolvedUrls(cardUrl, fallbackUrl);
274+
}
275+
276+
private record ResolvedUrls(String cardUrl, @Nullable String fallbackUrl) {}
277+
278+
// Intentionally limited: only strips trailing slashes. Both arguments are always
279+
// programmatically constructed URLs so case, port, and percent-encoding are consistent.
274280
private static boolean isSameUrl(String a, String b) {
275-
String stripSlash = b.endsWith("/") ? b.substring(0, b.length() - 1) : b;
276-
return a.equals(stripSlash);
281+
String normA = a.endsWith("/") ? a.substring(0, a.length() - 1) : a;
282+
String normB = b.endsWith("/") ? b.substring(0, b.length() - 1) : b;
283+
return normA.equals(normB);
277284
}
278285

279286
private AgentCard fetchAgentCard(String url) throws A2AClientError, A2AClientJSONError {

‎http-client/src/test/java/org/a2aproject/sdk/client/http/A2ACardResolverTest.java‎

Lines changed: 40 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -383,6 +383,43 @@ public void testGetAgentCard_doubleSlashBaseUrl_fallbackUrlNormalized() throws E
383383
assertEquals("http://example.com/", client.urlsCalled.get(1));
384384
}
385385

386+
@Test
387+
public void testGetAgentCard_doubleSlashWellKnownUrl_normalizedCardUrl() throws Exception {
388+
// A baseUrl that is already the well-known URL but with a double slash before /.well-known
389+
// must strip the well-known suffix and rebuild cleanly.
390+
TestHttpClient client = createTestClient();
391+
A2ACardResolver.builder().httpClient(client).baseUrl("http://example.com//.well-known/agent-card.json").build().getAgentCard();
392+
assertEquals(1, client.urlsCalled.size());
393+
assertEquals("http://example.com" + AGENT_CARD_PATH, client.urlsCalled.get(0));
394+
}
395+
396+
@Test
397+
public void testGetAgentCard_doubleSlashTenantCardUrl_sameTenant_normalizedCardUrl() throws Exception {
398+
// baseUrl is the tenant card URL with a double slash; tenant matches — must normalize cleanly.
399+
TestHttpClient client = createTestClient();
400+
A2ACardResolver.builder().httpClient(client)
401+
.baseUrl("http://example.com//.well-known/acme/agent-card.json")
402+
.tenant("acme")
403+
.build()
404+
.getAgentCard();
405+
assertEquals(1, client.urlsCalled.size());
406+
assertEquals("http://example.com/.well-known/acme/agent-card.json", client.urlsCalled.get(0));
407+
}
408+
409+
@Test
410+
public void testGetAgentCard_doubleSlashTenantCardUrl_differentTenant_normalizedCardUrl() throws Exception {
411+
// baseUrl is a tenant card URL with a double slash; a different tenant is requested — the
412+
// suffix must be stripped before the new tenant path is embedded.
413+
TestHttpClient client = createTestClient();
414+
A2ACardResolver.builder().httpClient(client)
415+
.baseUrl("http://example.com//.well-known/acme/agent-card.json")
416+
.tenant("foo")
417+
.build()
418+
.getAgentCard();
419+
assertEquals(1, client.urlsCalled.size());
420+
assertEquals("http://example.com/.well-known/foo/agent-card.json", client.urlsCalled.get(0));
421+
}
422+
386423
@Test
387424
public void testGetAgentCard_httpError_bothFail_throwsLastError() throws Exception {
388425
// Both primary (/.well-known/agent-card.json) and fallback return 404; last error is propagated
@@ -398,9 +435,10 @@ public void testGetAgentCard_httpError_bothFail_throwsLastError() throws Excepti
398435
assertEquals(404, ((A2AClientHTTPError) error.getSuppressed()[0]).getCode());
399436
}
400437

438+
401439
@Test
402-
public void testGetAgentCard_nonNotFound_httpError_noFallback() throws Exception {
403-
// Non-404 errors (e.g. 503) must not trigger the fallback — only 1 request made.
440+
public void testGetAgentCard_nonNotFound_noFallback() throws Exception {
441+
// A 5xx from the primary URL is not a URL-format issue, so no fallback is attempted.
404442
TestHttpClient client = createTestClient();
405443
client.status = 503;
406444
A2ACardResolver resolver = A2ACardResolver.builder().httpClient(client).baseUrl("http://example.com").build();

‎reference/jsonrpc/src/main/java/org/a2aproject/sdk/server/apps/quarkus/A2AServerRoutes.java‎

Lines changed: 9 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -72,11 +72,13 @@
7272
import org.a2aproject.sdk.server.extensions.A2AExtensions;
7373
import org.a2aproject.sdk.server.util.async.Internal;
7474
import org.a2aproject.sdk.server.util.sse.SseFormatter;
75+
import org.a2aproject.sdk.server.multitenancy.TenantNotFoundException;
7576
import org.a2aproject.sdk.spec.A2AError;
7677
import org.a2aproject.sdk.spec.InternalError;
7778
import org.a2aproject.sdk.spec.JSONParseError;
7879
import org.a2aproject.sdk.spec.TransportProtocol;
7980
import org.a2aproject.sdk.spec.UnsupportedOperationError;
81+
import org.a2aproject.sdk.spec.util.Utils;
8082
import org.a2aproject.sdk.transport.jsonrpc.handler.JSONRPCHandler;
8183
import org.jspecify.annotations.Nullable;
8284
import org.slf4j.Logger;
@@ -234,7 +236,7 @@ void setupRoutes(@Observes Router router) {
234236
.putHeader(CONTENT_TYPE, APPLICATION_JSON)
235237
.end(agentCard);
236238
} catch (JsonProcessingException e) {
237-
ctx.response().setStatusCode(500).end("Internal Server Error");
239+
ctx.response().setStatusCode(500).putHeader(CONTENT_TYPE, "text/plain").end("Internal Server Error");
238240
}
239241
});
240242

@@ -248,10 +250,12 @@ void setupRoutes(@Observes Router router) {
248250
.setStatusCode(200)
249251
.putHeader(CONTENT_TYPE, APPLICATION_JSON)
250252
.end(agentCard);
253+
} catch (TenantNotFoundException e) {
254+
ctx.response().setStatusCode(404).putHeader(CONTENT_TYPE, "text/plain").end(e.getResponseMessage());
251255
} catch (IllegalArgumentException e) {
252-
ctx.response().setStatusCode(400).end(e.getMessage());
256+
ctx.response().setStatusCode(400).putHeader(CONTENT_TYPE, "text/plain").end(e.getMessage());
253257
} catch (JsonProcessingException e) {
254-
ctx.response().setStatusCode(500).end("Internal Server Error");
258+
ctx.response().setStatusCode(500).putHeader(CONTENT_TYPE, "text/plain").end("Internal Server Error");
255259
}
256260
});
257261
}
@@ -439,15 +443,15 @@ public String getAgentCard(RoutingContext rc) throws JsonProcessingException {
439443
*
440444
* @param rc the Vert.x routing context (must contain a {@code tenant} path parameter)
441445
* @return the tenant-specific agent card as a JSON string
442-
* @throws IllegalArgumentException if the {@code tenant} path parameter is absent
446+
* @throws IllegalArgumentException if the tenant contains invalid characters
443447
* @throws JsonProcessingException if serialization fails
444448
*/
445449
public String getTenantAgentCard(RoutingContext rc) throws JsonProcessingException {
446-
// Route is /.well-known/{tenant}/agent-card.json — the named capture group must be present.
447450
String tenant = rc.pathParam("tenant");
448451
if (tenant == null) {
449452
throw new IllegalArgumentException("Missing tenant path parameter");
450453
}
454+
Utils.validateTenant(tenant);
451455
cacheMetadata.getHttpHeadersMap().forEach((k, v) -> rc.response().putHeader(k, v));
452456
return JsonUtil.toJson(jsonRpcHandler.getAgentCard(tenant));
453457
}

‎server-common/src/main/java/org/a2aproject/sdk/server/multitenancy/AgentCardRouter.java‎

Lines changed: 10 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -6,8 +6,9 @@
66
/**
77
* Resolves tenant-specific {@link AgentCard} instances.
88
* <p>
9-
* Implementations should return the default (unqualified) card when the tenant
10-
* is {@code null}, blank, or does not match any registered tenant.
9+
* Implementations should return the default public card when the tenant is {@code null}
10+
* or blank. When a non-blank tenant is provided and no matching card exists,
11+
* implementations should return {@code null}; the caller will treat that as a 404.
1112
*/
1213
public interface AgentCardRouter {
1314

@@ -22,13 +23,15 @@ public interface AgentCardRouter {
2223
/**
2324
* Resolves the public {@link AgentCard} for the given tenant.
2425
* <p>
25-
* Returns {@code null} by default, signaling the handler to fall back to the
26-
* default (non-tenant-specific) public agent card injected via {@code @PublicAgentCard}.
27-
* Implementations that manage tenant-specific public cards should return
28-
* a non-{@code null} card for known tenants.
26+
* Implementations should return the default public card when {@code tenant} is
27+
* {@code null} or blank, the tenant-specific card when a match is found, and
28+
* {@code null} when a non-blank tenant has no matching card — the caller treats
29+
* that as HTTP 404.
30+
* <p>
31+
* The default implementation returns {@code null} (no public-card routing configured).
2932
*
3033
* @param tenant the tenant identifier, may be {@code null}
31-
* @return the tenant-specific public agent card, or {@code null} to fall back to the default public card
34+
* @return the public agent card, or {@code null} if a non-blank tenant is unknown
3235
*/
3336
default @Nullable AgentCard resolvePublicCard(@Nullable String tenant) {
3437
return null;
Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
package org.a2aproject.sdk.server.multitenancy;
2+
3+
/**
4+
* Thrown when a tenant-specific public agent card is requested but no card is registered
5+
* for that tenant. Callers should map this to an HTTP 404 response.
6+
*/
7+
public class TenantNotFoundException extends RuntimeException {
8+
9+
private static final String MESSAGE_PREFIX = "No public agent card registered for tenant: ";
10+
11+
private final String tenant;
12+
13+
public TenantNotFoundException(String tenant) {
14+
super(MESSAGE_PREFIX + tenant);
15+
this.tenant = tenant;
16+
}
17+
18+
public String getTenant() {
19+
return tenant;
20+
}
21+
22+
/**
23+
* Returns the response body text for this exception (guaranteed non-null).
24+
*
25+
* @return the response message
26+
*/
27+
public String getResponseMessage() {
28+
return MESSAGE_PREFIX + tenant;
29+
}
30+
}

‎spec/src/main/java/org/a2aproject/sdk/spec/util/Utils.java‎

Lines changed: 8 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -301,12 +301,16 @@ public static void validateTenant(@Nullable String tenant) {
301301
}
302302

303303
/**
304-
* Normalizes a tenant identifier by stripping any leading or trailing slashes.
304+
* Builds the standard well-known path for a tenant-specific agent card.
305305
*
306-
* @param tenant the tenant to normalize, must not be null
307-
* @return the normalized tenant identifier (e.g. {@code "acme"} for {@code "/acme/"})
306+
* @param tenant the tenant identifier, must not be null or blank
307+
* @return the card path (e.g. {@code "/.well-known/acme/agent-card.json"})
308308
*/
309-
public static String normalizeTenant(String tenant) {
309+
public static String buildTenantCardPath(String tenant) {
310+
return "/.well-known/" + normalizeTenant(tenant) + "/agent-card.json";
311+
}
312+
313+
static String normalizeTenant(String tenant) {
310314
String stripped = tenant;
311315
if (stripped.startsWith("/")) {
312316
stripped = stripped.substring(1);

‎spec/src/test/java/org/a2aproject/sdk/spec/util/UtilsTest.java‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -407,4 +407,18 @@ void testStripWellKnownSuffix_invalidTenantCharsNotStripped() {
407407
assertEquals("http://example.com/.well-known/bad@tenant/agent-card.json",
408408
Utils.stripWellKnownSuffix("http://example.com/.well-known/bad@tenant/agent-card.json"));
409409
}
410+
411+
// -------------------------------------------------------------------------
412+
// buildTenantCardPath
413+
// -------------------------------------------------------------------------
414+
415+
@Test
416+
void testBuildTenantCardPath_simple() {
417+
assertEquals("/.well-known/acme/agent-card.json", Utils.buildTenantCardPath("acme"));
418+
}
419+
420+
@Test
421+
void testBuildTenantCardPath_stripsLeadingAndTrailingSlashes() {
422+
assertEquals("/.well-known/acme/agent-card.json", Utils.buildTenantCardPath("/acme/"));
423+
}
410424
}

0 commit comments

Comments
 (0)