Agent Mesh
Go a2aa2a-protocolagent-meshagentic-aiinferencemcpmeshmesh-networknetwork-securitynetworking-aip2p-network
node: relay agent card caching headers and send an ETag
Vitalii Cherepanovce11cc48cbb0
diff --git a/internal/node/a2a_service.go b/internal/node/a2a_service.goindex f639c9f6..042f43b9 100644--- a/internal/node/a2a_service.go+++ b/internal/node/a2a_service.go@@ -16,6 +16,8 @@ package nodeimport ("context"+ "crypto/sha256"+ "encoding/hex""encoding/json""fmt""io"@@ -171,12 +173,45 @@ func a2aServeAgentCard(node *AgentMeshNode, rt http.RoundTripper, w http.Responshttp.Error(w, "Internal Server Error", http.StatusInternalServerError)return true}+ // Caching (A2A 1.0, section 8.6.1): the agent's freshness and+ // modification time still describe the card, but its validator does not+ // once the content changed, so the node derives its own from the bytes it+ // serves and answers a matching If-None-Match itself.+ for _, h := range []string{"Cache-Control", "Last-Modified"} {+ if v := resp.Header.Get(h); v != "" {+ w.Header().Set(h, v)+ }+ }+ etag := agentCardETag(out)+ w.Header().Set("ETag", etag)+ if etagMatches(r.Header.Get("If-None-Match"), etag) {+ w.WriteHeader(http.StatusNotModified)+ return true+ }w.Header().Set("Content-Type", "application/json")w.Header().Set("Content-Length", strconv.Itoa(len(out)))_, _ = w.Write(out)return true}+// agentCardETag is a strong validator for the card bytes the node serves.+func agentCardETag(card []byte) string {+ sum := sha256.Sum256(card)+ return `"` + hex.EncodeToString(sum[:16]) + `"`+}++// etagMatches applies If-None-Match's weak comparison (RFC 9110, section+// 13.1.2) of a request header against the card's validator.+func etagMatches(header, etag string) bool {+ for _, candidate := range strings.Split(header, ",") {+ candidate = strings.TrimSpace(candidate)+ if candidate == "*" || strings.TrimPrefix(candidate, "W/") == etag {+ return true+ }+ }+ return false+}+// fetchRemoteAgentCard performs the mesh-side GET for the agent card, reusing// the headers already prepared for egress (biscuit, agent claim, passthrough// Authorization) on the incoming request.@@ -192,8 +227,12 @@ func fetchRemoteAgentCard(node *AgentMeshNode, rt http.RoundTripper, r *http.Req}req.Header = r.Header.Clone()// The node decodes the card itself, so negotiate identity encoding- // regardless of what the held client asked for.+ // regardless of what the held client asked for, and ask for the whole+ // card: the client's validators are for the card this node serves, which+ // the agent never saw.req.Header.Del("Accept-Encoding")+ req.Header.Del("If-None-Match")+ req.Header.Del("If-Modified-Since")req.Host = route.peerIDreturn (&http.Client{Transport: rt}).Do(req)}diff --git a/internal/node/a2a_service_test.go b/internal/node/a2a_service_test.goindex afa3e8c9..94d6bcbf 100644--- a/internal/node/a2a_service_test.go+++ b/internal/node/a2a_service_test.go@@ -16,6 +16,8 @@ package nodeimport ("context"+ "crypto/sha256"+ "encoding/hex""encoding/json""errors""io"@@ -408,3 +410,69 @@ func TestA2AEgressHookUppercaseTypeIsGated(t *testing.T) {t.Fatal("labels header must be stripped on a2a paths regardless of case")}}++// TestA2AServeAgentCardCaching pins the card's HTTP caching through the mesh+// (A2A 1.0, section 8.6.1): the agent's Cache-Control and Last-Modified reach+// the client, the validator matches the regenerated bytes rather than the+// agent's, and a client revalidating with it gets 304.+func TestA2AServeAgentCardCaching(t *testing.T) {+ const upstreamCard = `{"name":"T","version":"1.0.0","supportedInterfaces":[{"url":"http://localhost:7777","protocolBinding":"JSONRPC"}]}`+ var outbound *http.Request+ rt := roundTripFunc(func(r *http.Request) (*http.Response, error) {+ outbound = r+ resp := cardResponse(http.StatusOK, upstreamCard)+ resp.Header.Set("Cache-Control", "max-age=300")+ resp.Header.Set("Last-Modified", "Mon, 12 Oct 2026 08:00:00 GMT")+ resp.Header.Set("ETag", `"agent-v1"`)+ return resp, nil+ })+ get := func(ifNoneMatch string) *httptest.ResponseRecorder {+ t.Helper()+ rec := httptest.NewRecorder()+ req := httptest.NewRequest("GET", "/mesh/12D3KooWpeer/a2a/agent/.well-known/agent-card.json", nil)+ req.Host = "127.0.0.1:8080"+ if ifNoneMatch != "" {+ req.Header.Set("If-None-Match", ifNoneMatch)+ req.Header.Set("If-Modified-Since", "Mon, 12 Oct 2026 08:00:00 GMT")+ }+ if !serveEgressLocally(nil, rt, rec, req) {+ t.Fatal("card GET must be handled locally")+ }+ return rec+ }++ first := get("")+ if first.Code != http.StatusOK {+ t.Fatalf("status = %d, want 200", first.Code)+ }+ if got := first.Header().Get("Cache-Control"); got != "max-age=300" {+ t.Errorf("Cache-Control = %q, want the agent's max-age=300", got)+ }+ if got := first.Header().Get("Last-Modified"); got != "Mon, 12 Oct 2026 08:00:00 GMT" {+ t.Errorf("Last-Modified = %q, want the agent's", got)+ }+ etag := first.Header().Get("ETag")+ if etag == "" || etag == `"agent-v1"` {+ t.Fatalf("ETag = %q, want a validator of the regenerated card, not the agent's", etag)+ }+ sum := sha256.Sum256(first.Body.Bytes())+ if want := `"` + hex.EncodeToString(sum[:16]) + `"`; etag != want {+ t.Errorf("ETag = %q, want %q for the served bytes", etag, want)+ }++ for _, header := range []string{etag, "W/" + etag, `"other", ` + etag, "*"} {+ again := get(header)+ if again.Code != http.StatusNotModified {+ t.Errorf("If-None-Match %s: status = %d, want 304", header, again.Code)+ }+ if again.Body.Len() != 0 {+ t.Errorf("If-None-Match %s: 304 carries a body", header)+ }+ if outbound.Header.Get("If-None-Match") != "" || outbound.Header.Get("If-Modified-Since") != "" {+ t.Errorf("If-None-Match %s: the node's own fetch must ask the agent for the whole card", header)+ }+ }+ if stale := get(`"agent-v1"`); stale.Code != http.StatusOK {+ t.Errorf("If-None-Match with the agent's validator: status = %d, want 200", stale.Code)+ }+}