Skip to content

Agent Mesh

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.go
index f639c9f6..042f43b9 100644
--- a/internal/node/a2a_service.go
+++ b/internal/node/a2a_service.go
@@ -16,6 +16,8 @@ package node
import (
"context"
+ "crypto/sha256"
+ "encoding/hex"
"encoding/json"
"fmt"
"io"
@@ -171,12 +173,45 @@ func a2aServeAgentCard(node *AgentMeshNode, rt http.RoundTripper, w http.Respons
http.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.peerID
return (&http.Client{Transport: rt}).Do(req)
}
diff --git a/internal/node/a2a_service_test.go b/internal/node/a2a_service_test.go
index afa3e8c9..94d6bcbf 100644
--- a/internal/node/a2a_service_test.go
+++ b/internal/node/a2a_service_test.go
@@ -16,6 +16,8 @@ package node
import (
"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)
+ }
+}