From d56e9926b7095abbcfd426711aa61a6a482c385f Mon Sep 17 00:00:00 2001
From: gulldan <5641375+gulldan@users.noreply.github.com>
Date: Sat, 31 Oct 2026 13:20:16 +0300
Subject: [PATCH 01/14] fix(client): report the HTTP status of a non-JSON-RPC
error response
The JSON-RPC transport never looked at the status of a response. An
error that something in front of the agent answers itself (an
authenticating proxy's 401, a gateway's 429 or 502) carries no
JSON-RPC envelope, so the caller got "failed to parse JSON-RPC
response" and could not tell a credential or rate-limit problem from
a broken server. A streaming call answered that way without a content
type was handed to the SSE parser and came back as an empty stream.
A body that is not a JSON-RPC envelope is now reported with its
status, as the REST transport already does ("HTTP 429 Too Many
Requests:
"); a JSON-RPC envelope is still decoded whatever the
status, and a non-success status is never treated as a stream.
Fixes: #404
Co-Authored-By: Claude Opus 5.5
Signed-off-by: gulldan <5641375+gulldan@users.noreply.github.com>
---
a2a-client/src/jsonrpc.rs | 107 +++++++++++++++++++++++++++++++++-----
1 file changed, 93 insertions(+), 14 deletions(-)
diff --git a/a2a-client/src/jsonrpc.rs b/a2a-client/src/jsonrpc.rs
index 79887b9e..6d3cf3ae 100644
--- a/a2a-client/src/jsonrpc.rs
+++ b/a2a-client/src/jsonrpc.rs
@@ -35,6 +35,22 @@ fn parse_jsonrpc_error(err: JsonRpcError) -> A2AError {
crate::a2a_error_from_details(err.code, err.message, details)
}
+/// Parses a JSON-RPC envelope. A body that is not one, sent with a non-success
+/// status (an authenticating proxy's 401, a gateway's 429 or 502), is reported
+/// with that status, as the REST transport reports it.
+fn parse_jsonrpc_response(
+ status: reqwest::StatusCode,
+ body: &str,
+) -> Result {
+ serde_json::from_str(body).map_err(|e| {
+ if status.is_success() {
+ A2AError::internal(format!("failed to parse JSON-RPC response: {e}"))
+ } else {
+ A2AError::internal(format!("HTTP {status}: {body}"))
+ }
+ })
+}
+
/// JSON-RPC transport implementation.
///
/// Sends all requests as JSON-RPC 2.0 POSTs to a single endpoint.
@@ -67,6 +83,7 @@ impl JsonRpcTransport {
}
let response = wire::send(&self.client, builder.json(&rpc_request)).await?;
+ let status = response.status();
// Read the body as text first so the raw bytes can be logged before
// they become a typed value; one error message still covers both a
@@ -74,8 +91,7 @@ impl JsonRpcTransport {
let body = wire::response_text(response)
.await
.map_err(|e| A2AError::internal(format!("failed to parse JSON-RPC response: {e}")))?;
- let rpc_response: JsonRpcResponse = serde_json::from_str(&body)
- .map_err(|e| A2AError::internal(format!("failed to parse JSON-RPC response: {e}")))?;
+ let rpc_response = parse_jsonrpc_response(status, &body)?;
if let Some(err) = rpc_response.error {
return Err(parse_jsonrpc_error(err));
@@ -150,14 +166,16 @@ impl JsonRpcTransport {
// in the envelope rather than via status code. Detect that case by
// content type before handing the body to the SSE parser, which
// would otherwise find no `data:` frames and yield an empty stream.
- // A response with no content type is still treated as a stream:
+ // A success with no content type is still treated as a stream:
// reading it to inspect it would hang on a stream that has not sent
- // anything yet.
- let is_event_stream = response
- .headers()
- .get(reqwest::header::CONTENT_TYPE)
- .map(|v| v.as_bytes().starts_with(b"text/event-stream"))
- .unwrap_or(true);
+ // anything yet. A non-success status is never a stream.
+ let status = response.status();
+ let is_event_stream = status.is_success()
+ && response
+ .headers()
+ .get(reqwest::header::CONTENT_TYPE)
+ .map(|v| v.as_bytes().starts_with(b"text/event-stream"))
+ .unwrap_or(true);
if is_event_stream {
let stream = response.bytes_stream();
@@ -166,9 +184,7 @@ impl JsonRpcTransport {
let body = wire::response_text(response).await.map_err(|e| {
A2AError::internal(format!("failed to parse JSON-RPC response: {e}"))
})?;
- let rpc_response: JsonRpcResponse = serde_json::from_str(&body).map_err(|e| {
- A2AError::internal(format!("failed to parse JSON-RPC response: {e}"))
- })?;
+ let rpc_response = parse_jsonrpc_response(status, &body)?;
match rpc_response.error {
Some(err) => Err(parse_jsonrpc_error(err)),
@@ -525,12 +541,12 @@ impl Transport for JsonRpcTransport {
}
let response = wire::send(&self.client, builder.json(&rpc_request)).await?;
+ let status = response.status();
let body = wire::response_text(response)
.await
.map_err(|e| A2AError::internal(format!("failed to parse JSON-RPC response: {e}")))?;
- let rpc_response: JsonRpcResponse = serde_json::from_str(&body)
- .map_err(|e| A2AError::internal(format!("failed to parse JSON-RPC response: {e}")))?;
+ let rpc_response = parse_jsonrpc_response(status, &body)?;
if let Some(err) = rpc_response.error {
return Err(parse_jsonrpc_error(err));
@@ -657,6 +673,25 @@ mod tests {
format!("http://{addr}")
}
+ /// Answers one request with `status` and a body that is not JSON-RPC, as an
+ /// authenticating proxy or a gateway in front of the agent does.
+ async fn spawn_http_error_server(status: &'static str, body: &'static str) -> String {
+ let listener = TcpListener::bind("127.0.0.1:0").await.unwrap();
+ let addr = listener.local_addr().unwrap();
+
+ tokio::spawn(async move {
+ let (mut socket, _) = listener.accept().await.unwrap();
+ let _request = read_http_request(&mut socket).await;
+ let response = format!(
+ "HTTP/1.1 {status}\r\ncontent-length: {}\r\nconnection: close\r\n\r\n{body}",
+ body.len(),
+ );
+ socket.write_all(response.as_bytes()).await.unwrap();
+ });
+
+ format!("http://{addr}")
+ }
+
async fn read_http_request(socket: &mut TcpStream) -> String {
let mut buffer = Vec::new();
let mut chunk = [0_u8; 1024];
@@ -1502,6 +1537,50 @@ mod tests {
assert!(error.message.contains("failed to parse JSON-RPC response"));
}
+ #[tokio::test]
+ async fn test_http_error_without_jsonrpc_body_reports_the_status() {
+ let endpoint = spawn_http_error_server("429 Too Many Requests", "budget exceeded").await;
+ let transport =
+ JsonRpcTransport::new(crate::default_reqwest_client(None).unwrap(), endpoint);
+
+ let error = transport
+ .get_task(
+ &ServiceParams::new(),
+ &GetTaskRequest {
+ id: "task-1".into(),
+ history_length: None,
+ tenant: None,
+ },
+ )
+ .await
+ .unwrap_err();
+
+ assert_eq!(error.code, error_code::INTERNAL_ERROR);
+ assert_eq!(error.message, "HTTP 429 Too Many Requests: budget exceeded");
+ }
+
+ #[tokio::test]
+ async fn test_streaming_http_error_reports_the_status_not_an_empty_stream() {
+ // No content type, so the status is the only thing marking it as no stream.
+ let endpoint = spawn_http_error_server("401 Unauthorized", "").await;
+ let transport =
+ JsonRpcTransport::new(crate::default_reqwest_client(None).unwrap(), endpoint);
+
+ let req = SubscribeToTaskRequest {
+ id: "task-1".into(),
+ tenant: None,
+ };
+ let error = match transport
+ .subscribe_to_task(&ServiceParams::new(), &req)
+ .await
+ {
+ Err(e) => e,
+ Ok(_) => panic!("expected error, got a stream"),
+ };
+
+ assert_eq!(error.message, "HTTP 401 Unauthorized: ");
+ }
+
#[tokio::test]
async fn test_create_push_config_rejects_missing_result() {
let response = json!({
From 70f0f45658eefc229e52011417c6b067e0fb420a Mon Sep 17 00:00:00 2001
From: gulldan <5641375+gulldan@users.noreply.github.com>
Date: Sat, 31 Oct 2026 18:20:02 +0300
Subject: [PATCH 02/14] test(client): take the subscribe error without an
unreachable arm
The streaming test matched on the result and panicked in an `Ok` arm that a
passing run never reaches, so that line stayed uncovered. Taking the error
with `.err().expect()` keeps the assertion and needs no `Debug` on the stream.
Co-Authored-By: Claude Opus 5.5
Signed-off-by: gulldan <5641375+gulldan@users.noreply.github.com>
---
a2a-client/src/jsonrpc.rs | 8 +++-----
1 file changed, 3 insertions(+), 5 deletions(-)
diff --git a/a2a-client/src/jsonrpc.rs b/a2a-client/src/jsonrpc.rs
index 6d3cf3ae..87ea8b0c 100644
--- a/a2a-client/src/jsonrpc.rs
+++ b/a2a-client/src/jsonrpc.rs
@@ -1570,13 +1570,11 @@ mod tests {
id: "task-1".into(),
tenant: None,
};
- let error = match transport
+ let error = transport
.subscribe_to_task(&ServiceParams::new(), &req)
.await
- {
- Err(e) => e,
- Ok(_) => panic!("expected error, got a stream"),
- };
+ .err()
+ .expect("expected error, got a stream");
assert_eq!(error.message, "HTTP 401 Unauthorized: ");
}
From 9e749f4c2c1c45607a753eeabce27dae8ac5e76d Mon Sep 17 00:00:00 2001
From: gulldan <5641375+gulldan@users.noreply.github.com>
Date: Sat, 31 Oct 2026 13:20:13 +0300
Subject: [PATCH 03/14] fix(a2a-pb): decode integral Value numbers as integers
google.protobuf.Value carries every number as a double, and
proto_value_to_json_value turned each one back into a JSON float, so
an integer in a data part or in metadata reached the executor, and a
client's decoded response, as 3600.0. serde then refuses it for an
integer type ("invalid type: floating point `3600.0`, expected u32").
A whole number within +-2^53, where a double is exact, is now given
back as an integer; other numbers stay floats. The round-trip tests
that used floats to work around this now use integers, and a new
protojson test decodes a JSON-RPC SendMessage whose data part holds an
integer and deserializes it into u32.
Fixes: #399
Co-Authored-By: Claude Opus 5.5
Signed-off-by: gulldan <5641375+gulldan@users.noreply.github.com>
---
a2a-pb/src/pbconv.rs | 26 +++++++++++++++++---------
a2a-pb/tests/protojson.rs | 23 +++++++++++++++++++++++
2 files changed, 40 insertions(+), 9 deletions(-)
diff --git a/a2a-pb/src/pbconv.rs b/a2a-pb/src/pbconv.rs
index 64e561ad..ef8840eb 100644
--- a/a2a-pb/src/pbconv.rs
+++ b/a2a-pb/src/pbconv.rs
@@ -64,9 +64,7 @@ pub fn proto_value_to_json_value(v: &prost_types::Value) -> Value {
match &v.kind {
Some(Kind::NullValue(_)) => Value::Null,
Some(Kind::BoolValue(b)) => Value::Bool(*b),
- Some(Kind::NumberValue(n)) => serde_json::Number::from_f64(*n)
- .map(Value::Number)
- .unwrap_or(Value::Null),
+ Some(Kind::NumberValue(n)) => json_number(*n).map(Value::Number).unwrap_or(Value::Null),
Some(Kind::StringValue(s)) => Value::String(s.clone()),
Some(Kind::ListValue(list)) => {
Value::Array(list.values.iter().map(proto_value_to_json_value).collect())
@@ -83,6 +81,18 @@ pub fn proto_value_to_json_value(v: &prost_types::Value) -> Value {
}
}
+/// `google.protobuf.Value` holds every number as a double, so an integer such
+/// as `3600` arrives as `3600.0`. A whole number within ±2^53, where a double
+/// is exact, is given back as an integer so it still deserializes into one.
+fn json_number(n: f64) -> Option {
+ const MAX_EXACT_INTEGER: f64 = 9_007_199_254_740_992.0;
+ if n.fract() == 0.0 && n.abs() <= MAX_EXACT_INTEGER {
+ Some((n as i64).into())
+ } else {
+ serde_json::Number::from_f64(n)
+ }
+}
+
/// Lowest `seconds` a `google.protobuf.Timestamp` may carry: `0001-01-01T00:00:00Z`.
const PROTO_TIMESTAMP_MIN_SECONDS: i64 = -62_135_596_800;
/// Highest `seconds` a `google.protobuf.Timestamp` may carry: `9999-12-31T23:59:59Z`.
@@ -1495,10 +1505,9 @@ mod tests {
fn test_struct_roundtrip() {
let mut map = HashMap::new();
map.insert("str".to_string(), Value::String("hello".to_string()));
- map.insert(
- "num".to_string(),
- Value::Number(serde_json::Number::from_f64(42.0).unwrap()),
- );
+ map.insert("num".to_string(), serde_json::json!(42));
+ map.insert("negative".to_string(), serde_json::json!(-7));
+ map.insert("fraction".to_string(), serde_json::json!(4.5));
map.insert("bool".to_string(), Value::Bool(true));
map.insert("null".to_string(), Value::Null);
let proto_s = to_proto_struct(&map);
@@ -2166,8 +2175,7 @@ mod tests {
#[test]
fn test_part_data_roundtrip() {
- // Use f64 numbers since proto Value stores all numbers as f64
- let data = serde_json::json!({"nested": [1.0, 2.0, 3.0]});
+ let data = serde_json::json!({"nested": [1, 2, 3], "ratio": 0.5});
let part = Part {
content: PartContent::Data(data),
filename: None,
diff --git a/a2a-pb/tests/protojson.rs b/a2a-pb/tests/protojson.rs
index 160809e9..b91a901a 100644
--- a/a2a-pb/tests/protojson.rs
+++ b/a2a-pb/tests/protojson.rs
@@ -313,3 +313,26 @@ fn stream_response_protojson_roundtrip_serializes_oneof_payloads() {
let roundtrip: StreamResponse = serde_json::from_value(json).unwrap();
assert_eq!(response, roundtrip);
}
+
+/// `google.protobuf.Value` carries every number as a double, so an integer in
+/// a data part has to come back out as an integer, not as `3600.0`.
+#[test]
+fn integers_in_data_parts_stay_integers() {
+ let request: a2a::SendMessageRequest = a2a_pb::protojson_conv::from_value(json!({
+ "message": {
+ "messageId": "msg-1",
+ "role": "ROLE_USER",
+ "parts": [{"data": {"sinceSeconds": 3600, "ratio": 0.5}}]
+ }
+ }))
+ .unwrap();
+
+ let a2a::PartContent::Data(data) = &request.message.parts[0].content else {
+ panic!("expected a data part");
+ };
+ assert_eq!(
+ serde_json::from_value::(data["sinceSeconds"].clone()).unwrap(),
+ 3600
+ );
+ assert_eq!(data["ratio"], json!(0.5));
+}
From 1997ab7d5d3e17d8d01bfbf1241576d5a4d0c2ec Mon Sep 17 00:00:00 2001
From: gulldan <5641375+gulldan@users.noreply.github.com>
Date: Sat, 31 Oct 2026 13:22:30 +0300
Subject: [PATCH 04/14] feat(server): bound the finished tasks
InMemoryTaskStore keeps
InMemoryTaskStore never removed a task, and TaskStore has no delete,
so a long-running agent kept every task it ever served: 20,000 tasks
with a 4 KiB artifact each held 192 MiB.
InMemoryTaskStore::with_terminal_task_limit(n) keeps at most n tasks
in a terminal state and purges the one that reached its terminal state
earliest. Tasks that are not terminal are never purged, and a purged
task reads as TaskNotFoundError, which A2A 3.3.2 allows for a task
that was completed and purged. new() keeps every task, as before. With
a limit of 1,000 the same run stays at about 20 MiB.
Fixes: #401
Co-Authored-By: Claude Opus 5.5
Signed-off-by: gulldan <5641375+gulldan@users.noreply.github.com>
---
a2a-server/src/task_store/inmemory.rs | 124 ++++++++++++++++++++++++--
1 file changed, 116 insertions(+), 8 deletions(-)
diff --git a/a2a-server/src/task_store/inmemory.rs b/a2a-server/src/task_store/inmemory.rs
index 93878f4e..e8b7e270 100644
--- a/a2a-server/src/task_store/inmemory.rs
+++ b/a2a-server/src/task_store/inmemory.rs
@@ -3,7 +3,7 @@
// SPDX-License-Identifier: Apache-2.0
use a2a::*;
use async_trait::async_trait;
-use std::collections::HashMap;
+use std::collections::{HashMap, VecDeque};
use tokio::sync::RwLock;
use super::apply_history_length;
@@ -15,17 +15,54 @@ struct StoredEntry {
version: TaskVersion,
}
+#[derive(Default)]
+struct Tasks {
+ entries: HashMap,
+ /// Terminal task ids, oldest first; tracked only under a limit.
+ terminal: VecDeque,
+}
+
+impl Tasks {
+ /// Records that `id` reached a terminal state, then purges the tasks that
+ /// reached one earliest until at most `limit` remain.
+ fn retire(&mut self, id: &str, limit: Option) {
+ let Some(limit) = limit else {
+ return;
+ };
+ self.terminal.push_back(id.to_string());
+ while self.terminal.len() > limit {
+ if let Some(oldest) = self.terminal.pop_front() {
+ self.entries.remove(&oldest);
+ }
+ }
+ }
+}
+
/// In-memory task store. Contents do not survive restarts.
+///
+/// Keeps every task for the life of the process unless
+/// [`Self::with_terminal_task_limit`] bounds how many finished ones it holds.
pub struct InMemoryTaskStore {
- tasks: RwLock>,
+ tasks: RwLock,
+ terminal_task_limit: Option,
}
impl InMemoryTaskStore {
pub fn new() -> Self {
InMemoryTaskStore {
- tasks: RwLock::new(HashMap::new()),
+ tasks: RwLock::new(Tasks::default()),
+ terminal_task_limit: None,
}
}
+
+ /// Keep at most `limit` tasks in a terminal state, purging the one that
+ /// reached its terminal state earliest first. A purged task is reported
+ /// as `TaskNotFoundError`, which §3.3.2 allows for a completed and purged
+ /// task. Tasks that are not terminal are never purged.
+ pub fn with_terminal_task_limit(mut self, limit: usize) -> Self {
+ self.terminal_task_limit = Some(limit);
+ self
+ }
}
impl Default for InMemoryTaskStore {
@@ -38,17 +75,24 @@ impl Default for InMemoryTaskStore {
impl TaskStore for InMemoryTaskStore {
async fn create(&self, task: Task) -> Result {
let mut store = self.tasks.write().await;
- if store.contains_key(&task.id) {
+ if store.entries.contains_key(&task.id) {
return Err(crate::sanitized_internal_error("task already exists"));
}
let id = task.id.clone();
- store.insert(id, StoredEntry { task, version: 1 });
+ let terminal = task.status.state.is_terminal();
+ store
+ .entries
+ .insert(id.clone(), StoredEntry { task, version: 1 });
+ if terminal {
+ store.retire(&id, self.terminal_task_limit);
+ }
Ok(1)
}
async fn update(&self, task: Task) -> Result {
let mut store = self.tasks.write().await;
let entry = store
+ .entries
.get_mut(&task.id)
.ok_or_else(|| A2AError::task_not_found(&task.id))?;
// A terminal task's state is immutable. Re-applying the same
@@ -61,9 +105,15 @@ impl TaskStore for InMemoryTaskStore {
task.id, entry.task.status.state, task.status.state
)));
}
+ let retired = !entry.task.status.state.is_terminal() && task.status.state.is_terminal();
entry.version += 1;
entry.task = task;
- Ok(entry.version)
+ let version = entry.version;
+ if retired {
+ let id = entry.task.id.clone();
+ store.retire(&id, self.terminal_task_limit);
+ }
+ Ok(version)
}
async fn begin_cancel(&self, task_id: &str) -> Result {
@@ -72,6 +122,7 @@ impl TaskStore for InMemoryTaskStore {
// window.
let mut store = self.tasks.write().await;
let entry = store
+ .entries
.get_mut(task_id)
.ok_or_else(|| A2AError::task_not_found(task_id))?;
if entry.task.status.state.is_terminal() {
@@ -80,17 +131,20 @@ impl TaskStore for InMemoryTaskStore {
entry.version += 1;
entry.task.status.state = TaskState::Canceled;
entry.task.status.timestamp = Some(chrono::Utc::now());
- Ok(entry.task.clone())
+ let task = entry.task.clone();
+ store.retire(task_id, self.terminal_task_limit);
+ Ok(task)
}
async fn get(&self, task_id: &str) -> Result, A2AError> {
let store = self.tasks.read().await;
- Ok(store.get(task_id).map(|e| e.task.clone()))
+ Ok(store.entries.get(task_id).map(|e| e.task.clone()))
}
async fn list(&self, req: &ListTasksRequest) -> Result {
let store = self.tasks.read().await;
let mut tasks: Vec = store
+ .entries
.values()
.filter(|entry| {
// Filter by context_id if provided
@@ -309,6 +363,60 @@ mod tests {
assert_eq!(result.unwrap_err().code, error_code::TASK_NOT_FOUND);
}
+ #[tokio::test]
+ async fn test_terminal_task_limit_purges_the_oldest_finished_task() {
+ let store = InMemoryTaskStore::new().with_terminal_task_limit(2);
+ store
+ .create(make_task("working", "c1", TaskState::Working))
+ .await
+ .unwrap();
+ for id in ["t1", "t2", "t3"] {
+ store
+ .create(make_task(id, "c1", TaskState::Working))
+ .await
+ .unwrap();
+ store
+ .update(make_task(id, "c1", TaskState::Completed))
+ .await
+ .unwrap();
+ }
+ // Re-applying a terminal state does not count the task twice.
+ store
+ .update(make_task("t3", "c1", TaskState::Completed))
+ .await
+ .unwrap();
+
+ assert!(store.get("t1").await.unwrap().is_none());
+ assert!(store.get("t2").await.unwrap().is_some());
+ assert!(store.get("t3").await.unwrap().is_some());
+ assert!(store.get("working").await.unwrap().is_some());
+
+ store.begin_cancel("working").await.unwrap();
+ assert!(store.get("t2").await.unwrap().is_none());
+ assert!(store.get("working").await.unwrap().is_some());
+
+ store
+ .create(make_task("t4", "c1", TaskState::Failed))
+ .await
+ .unwrap();
+ assert!(store.get("t3").await.unwrap().is_none());
+ assert_eq!(store.tasks.read().await.entries.len(), 2);
+ }
+
+ #[tokio::test]
+ async fn test_unlimited_store_keeps_every_finished_task() {
+ let store = InMemoryTaskStore::new();
+ for i in 0..100 {
+ let id = format!("t{i}");
+ store
+ .create(make_task(&id, "c1", TaskState::Completed))
+ .await
+ .unwrap();
+ }
+ assert_eq!(store.tasks.read().await.entries.len(), 100);
+ assert!(store.tasks.read().await.terminal.is_empty());
+ }
+
#[tokio::test]
async fn test_get_not_found() {
let store = InMemoryTaskStore::new();
From 844bfb6a7a0762787f4d9f7b7c53ff6ef9ae8a65 Mon Sep 17 00:00:00 2001
From: gulldan <5641375+gulldan@users.noreply.github.com>
Date: Sat, 31 Oct 2026 14:12:39 +0300
Subject: [PATCH 05/14] fix(server): enforce A2A-Version on the REST and gRPC
bindings
Only the JSON-RPC binding read A2A-Version: HTTP+JSON and gRPC served
a request with `A2A-Version: 99.0`, or with no version at all, as a
1.0 request, although 3.6.2 requires every interface to answer
VersionNotSupportedError and to read an empty value as 0.3.
The JSON-RPC check moves unchanged to middleware::check_a2a_version.
rest_router runs it ahead of every route and, when the header is
absent, reads the A2A-Version query parameter that 3.6.1 allows
instead; GrpcHandler runs it on the metadata of every method. Both
answer with the existing VERSION_NOT_SUPPORTED mapping (400 /
FAILED_PRECONDITION). Tests that call the transports directly now send
the version, as the JSON-RPC ones already do.
Fixes: #410
Co-Authored-By: Claude Opus 5.5
Signed-off-by: gulldan <5641375+gulldan@users.noreply.github.com>
---
a2a-grpc/src/server.rs | 20 +++++
a2a-grpc/tests/e2e.rs | 69 +++++++++++++----
a2a-server/src/jsonrpc.rs | 29 +------
a2a-server/src/middleware.rs | 30 +++++++
a2a-server/src/rest.rs | 129 ++++++++++++++++++++++++++++++-
examples/tests/transports_e2e.rs | 74 +++++++++---------
6 files changed, 266 insertions(+), 85 deletions(-)
diff --git a/a2a-grpc/src/server.rs b/a2a-grpc/src/server.rs
index 1bb8b2ab..7a1bb721 100644
--- a/a2a-grpc/src/server.rs
+++ b/a2a-grpc/src/server.rs
@@ -52,6 +52,15 @@ fn extract_service_params(
params
}
+/// §3.6.2 for every gRPC method, on the `A2A-Version` read from metadata
+/// (§10.2) -- the same check the HTTP bindings apply.
+#[allow(clippy::result_large_err)]
+fn validate_protocol_version(
+ params: &a2a_server::middleware::ServiceParams,
+) -> Result<(), tonic::Status> {
+ a2a_server::middleware::check_a2a_version(params).map_err(|error| a2a_error_to_status(&error))
+}
+
#[allow(clippy::result_large_err)]
fn map_proto_stream_item(
item: Result,
@@ -69,6 +78,7 @@ impl A2aService for GrpcHandler {
request: tonic::Request,
) -> Result, tonic::Status> {
let params = extract_service_params(request.metadata());
+ validate_protocol_version(¶ms)?;
let native_req = pbconv::from_proto_send_message_request(request.get_ref());
let result = self
.handler
@@ -87,6 +97,7 @@ impl A2aService for GrpcHandler {
request: tonic::Request,
) -> Result, tonic::Status> {
let params = extract_service_params(request.metadata());
+ validate_protocol_version(¶ms)?;
let native_req = pbconv::from_proto_send_message_request(request.get_ref());
let stream = self
.handler
@@ -102,6 +113,7 @@ impl A2aService for GrpcHandler {
request: tonic::Request,
) -> Result, tonic::Status> {
let params = extract_service_params(request.metadata());
+ validate_protocol_version(¶ms)?;
let native_req = pbconv::from_proto_get_task_request(request.get_ref());
let result = self
.handler
@@ -116,6 +128,7 @@ impl A2aService for GrpcHandler {
request: tonic::Request,
) -> Result, tonic::Status> {
let params = extract_service_params(request.metadata());
+ validate_protocol_version(¶ms)?;
let native_req = pbconv::from_proto_list_tasks_request(request.get_ref());
let result = self
.handler
@@ -132,6 +145,7 @@ impl A2aService for GrpcHandler {
request: tonic::Request,
) -> Result, tonic::Status> {
let params = extract_service_params(request.metadata());
+ validate_protocol_version(¶ms)?;
let native_req = pbconv::from_proto_cancel_task_request(request.get_ref());
let result = self
.handler
@@ -148,6 +162,7 @@ impl A2aService for GrpcHandler {
request: tonic::Request,
) -> Result, tonic::Status> {
let params = extract_service_params(request.metadata());
+ validate_protocol_version(¶ms)?;
let native_req = pbconv::from_proto_subscribe_to_task_request(request.get_ref());
let stream = self
.handler
@@ -163,6 +178,7 @@ impl A2aService for GrpcHandler {
request: tonic::Request,
) -> Result, tonic::Status> {
let params = extract_service_params(request.metadata());
+ validate_protocol_version(¶ms)?;
let native_req =
pbconv::from_proto_create_task_push_notification_config_request(request.get_ref());
let result = self
@@ -180,6 +196,7 @@ impl A2aService for GrpcHandler {
request: tonic::Request,
) -> Result, tonic::Status> {
let params = extract_service_params(request.metadata());
+ validate_protocol_version(¶ms)?;
let native_req =
pbconv::from_proto_get_task_push_notification_config_request(request.get_ref());
let result = self
@@ -198,6 +215,7 @@ impl A2aService for GrpcHandler {
) -> Result, tonic::Status>
{
let params = extract_service_params(request.metadata());
+ validate_protocol_version(¶ms)?;
let native_req =
pbconv::from_proto_list_task_push_notification_configs_request(request.get_ref());
let result = self
@@ -215,6 +233,7 @@ impl A2aService for GrpcHandler {
request: tonic::Request,
) -> Result, tonic::Status> {
let params = extract_service_params(request.metadata());
+ validate_protocol_version(¶ms)?;
let native_req = pbconv::from_proto_get_extended_agent_card_request(request.get_ref());
let result = self
.handler
@@ -229,6 +248,7 @@ impl A2aService for GrpcHandler {
request: tonic::Request,
) -> Result, tonic::Status> {
let params = extract_service_params(request.metadata());
+ validate_protocol_version(¶ms)?;
let native_req =
pbconv::from_proto_delete_task_push_notification_config_request(request.get_ref());
self.handler
diff --git a/a2a-grpc/tests/e2e.rs b/a2a-grpc/tests/e2e.rs
index 5c27f308..8b2f9631 100644
--- a/a2a-grpc/tests/e2e.rs
+++ b/a2a-grpc/tests/e2e.rs
@@ -335,6 +335,12 @@ fn endpoint_without_scheme(endpoint: &str) -> String {
.unwrap_or_else(|| endpoint.to_string())
}
+/// A2A-Version a real client sends (§3.6.1): the server rejects a request
+/// without one (§3.6.2).
+fn versioned_params() -> ServiceParams {
+ ServiceParams::from([(SVC_PARAM_VERSION.to_string(), vec![VERSION.to_string()])])
+}
+
fn send_message_request() -> SendMessageRequest {
SendMessageRequest {
message: sample_message(Role::User, "hello"),
@@ -350,13 +356,13 @@ async fn grpc_transport_end_to_end() {
let transport = GrpcTransport::connect(endpoint).await.unwrap();
let send_resp = transport
- .send_message(&ServiceParams::new(), &send_message_request())
+ .send_message(&versioned_params(), &send_message_request())
.await;
assert!(matches!(send_resp.unwrap(), SendMessageResponse::Task(_)));
let task = transport
.get_task(
- &ServiceParams::new(),
+ &versioned_params(),
&GetTaskRequest {
id: "task-1".to_string(),
history_length: Some(1),
@@ -369,7 +375,7 @@ async fn grpc_transport_end_to_end() {
let list = transport
.list_tasks(
- &ServiceParams::new(),
+ &versioned_params(),
&ListTasksRequest {
context_id: Some("ctx-1".to_string()),
status: Some(TaskState::Completed),
@@ -387,7 +393,7 @@ async fn grpc_transport_end_to_end() {
let canceled = transport
.cancel_task(
- &ServiceParams::new(),
+ &versioned_params(),
&CancelTaskRequest {
id: "task-1".to_string(),
metadata: None,
@@ -399,14 +405,14 @@ async fn grpc_transport_end_to_end() {
assert_eq!(canceled.status.state, TaskState::Canceled);
let created = transport
- .create_push_config(&ServiceParams::new(), &sample_push_config("cfg-1"))
+ .create_push_config(&versioned_params(), &sample_push_config("cfg-1"))
.await
.unwrap();
assert_eq!(created.id.as_deref(), Some("cfg-1"));
let fetched = transport
.get_push_config(
- &ServiceParams::new(),
+ &versioned_params(),
&GetTaskPushNotificationConfigRequest {
task_id: "task-1".to_string(),
id: "cfg-1".to_string(),
@@ -419,7 +425,7 @@ async fn grpc_transport_end_to_end() {
let configs = transport
.list_push_configs(
- &ServiceParams::new(),
+ &versioned_params(),
&ListTaskPushNotificationConfigsRequest {
task_id: "task-1".to_string(),
page_size: Some(10),
@@ -433,7 +439,7 @@ async fn grpc_transport_end_to_end() {
transport
.delete_push_config(
- &ServiceParams::new(),
+ &versioned_params(),
&DeleteTaskPushNotificationConfigRequest {
task_id: "task-1".to_string(),
id: "cfg-1".to_string(),
@@ -445,7 +451,7 @@ async fn grpc_transport_end_to_end() {
let card = transport
.get_extended_agent_card(
- &ServiceParams::new(),
+ &versioned_params(),
&GetExtendedAgentCardRequest { tenant: None },
)
.await
@@ -462,7 +468,7 @@ async fn grpc_transport_streaming_and_error_paths() {
let transport = GrpcTransport::connect(endpoint.clone()).await.unwrap();
let stream = transport
- .send_streaming_message(&ServiceParams::new(), &send_message_request())
+ .send_streaming_message(&versioned_params(), &send_message_request())
.await
.unwrap();
let events: Vec<_> = stream.collect().await;
@@ -474,7 +480,7 @@ async fn grpc_transport_streaming_and_error_paths() {
let subscribe_stream = transport
.subscribe_to_task(
- &ServiceParams::new(),
+ &versioned_params(),
&SubscribeToTaskRequest {
id: "task-1".to_string(),
tenant: None,
@@ -487,7 +493,7 @@ async fn grpc_transport_streaming_and_error_paths() {
let err = transport
.get_task(
- &ServiceParams::new(),
+ &versioned_params(),
&GetTaskRequest {
id: "missing".to_string(),
history_length: None,
@@ -500,7 +506,7 @@ async fn grpc_transport_streaming_and_error_paths() {
let err = transport
.delete_push_config(
- &ServiceParams::new(),
+ &versioned_params(),
&DeleteTaskPushNotificationConfigRequest {
task_id: "task-1".to_string(),
id: "missing".to_string(),
@@ -533,7 +539,7 @@ async fn grpc_transport_accepts_bare_host_port_endpoints() {
let transport = GrpcTransport::connect(bare_endpoint.clone()).await.unwrap();
let task = transport
.get_task(
- &ServiceParams::new(),
+ &versioned_params(),
&GetTaskRequest {
id: "task-1".to_string(),
history_length: Some(1),
@@ -553,7 +559,7 @@ async fn grpc_transport_accepts_bare_host_port_endpoints() {
.await
.unwrap();
let response = transport
- .send_message(&ServiceParams::new(), &send_message_request())
+ .send_message(&versioned_params(), &send_message_request())
.await
.unwrap();
assert!(matches!(response, SendMessageResponse::Task(_)));
@@ -569,7 +575,7 @@ async fn grpc_transport_treats_zero_page_size_as_unset() {
let sent = transport
.send_message(
- &ServiceParams::new(),
+ &versioned_params(),
&SendMessageRequest {
message: Message::new(Role::User, vec![Part::text("hello")]),
configuration: None,
@@ -587,7 +593,7 @@ async fn grpc_transport_treats_zero_page_size_as_unset() {
let listed = transport
.list_tasks(
- &ServiceParams::new(),
+ &versioned_params(),
&ListTasksRequest {
context_id: Some(task.context_id.clone()),
status: None,
@@ -609,3 +615,32 @@ async fn grpc_transport_treats_zero_page_size_as_unset() {
transport.destroy().await.unwrap();
handle.abort();
}
+
+#[tokio::test]
+async fn grpc_transport_rejects_unsupported_a2a_version() {
+ let (endpoint, handle) = spawn_grpc_server().await;
+ let transport = GrpcTransport::connect(endpoint).await.unwrap();
+
+ // §3.6.2: 99.0 is unsupported, and an absent version is "0.3".
+ let unsupported =
+ ServiceParams::from([(SVC_PARAM_VERSION.to_string(), vec!["99.0".to_string()])]);
+ for params in [unsupported, ServiceParams::new()] {
+ let err = transport
+ .send_message(¶ms, &send_message_request())
+ .await
+ .unwrap_err();
+ assert_eq!(err.code, error_code::VERSION_NOT_SUPPORTED, "{params:?}");
+
+ let err = match transport
+ .send_streaming_message(¶ms, &send_message_request())
+ .await
+ {
+ Ok(_) => panic!("streaming accepted {params:?}"),
+ Err(err) => err,
+ };
+ assert_eq!(err.code, error_code::VERSION_NOT_SUPPORTED, "{params:?}");
+ }
+
+ transport.destroy().await.unwrap();
+ handle.abort();
+}
diff --git a/a2a-server/src/jsonrpc.rs b/a2a-server/src/jsonrpc.rs
index 0272c68c..87222cbb 100644
--- a/a2a-server/src/jsonrpc.rs
+++ b/a2a-server/src/jsonrpc.rs
@@ -16,7 +16,7 @@ use futures::{StreamExt, stream::BoxStream};
use serde_json::Value;
use crate::handler::RequestHandler;
-use crate::middleware::{ServiceParams, extract_service_params};
+use crate::middleware::{ServiceParams, check_a2a_version, extract_service_params};
use crate::sse;
/// Shared state for the JSON-RPC handler.
@@ -287,33 +287,6 @@ fn invalid_params(e: impl std::fmt::Display) -> A2AError {
A2AError::invalid_params(format!("invalid params: {e}"))
}
-/// The major version this build implements (§3.6.2). Minor is accepted
-/// unconditionally since nothing here branches on it.
-const SUPPORTED_MAJOR_VERSION: u32 = 1;
-
-/// Mirrors a2acli's own `parse_protocol_version`: tolerant of a bare major,
-/// extra trailing components, and surrounding whitespace.
-fn parse_major_version(value: &str) -> Option {
- value.trim().split('.').next()?.parse().ok()
-}
-
-/// §3.6.2: reject a request whose `A2A-Version` header names an
-/// unsupported major version. §3.6.1/§3.6.2 both require an absent header
-/// to be interpreted as "0.3", not as "whatever this interface happens to
-/// serve" -- so it's rejected here exactly like any other unsupported
-/// version, rather than silently processed as this build's version.
-fn check_a2a_version(params: &ServiceParams) -> Result<(), A2AError> {
- let requested = params
- .get("a2a-version")
- .and_then(|v| v.first())
- .map(String::as_str)
- .unwrap_or("0.3");
- match parse_major_version(requested) {
- Some(SUPPORTED_MAJOR_VERSION) => Ok(()),
- _ => Err(A2AError::version_not_supported(requested)),
- }
-}
-
#[cfg(test)]
mod tests {
use super::*;
diff --git a/a2a-server/src/middleware.rs b/a2a-server/src/middleware.rs
index 51435824..d328f10e 100644
--- a/a2a-server/src/middleware.rs
+++ b/a2a-server/src/middleware.rs
@@ -10,6 +10,36 @@ use std::collections::HashMap;
/// Service parameters — metadata from HTTP headers or gRPC metadata.
pub type ServiceParams = HashMap>;
+/// The major version this build implements (§3.6.2). Minor is accepted
+/// unconditionally since nothing here branches on it.
+const SUPPORTED_MAJOR_VERSION: u32 = 1;
+
+/// Mirrors a2acli's own `parse_protocol_version`: tolerant of a bare major,
+/// extra trailing components, and surrounding whitespace.
+fn parse_major_version(value: &str) -> Option {
+ value.trim().split('.').next()?.parse().ok()
+}
+
+/// §3.6.2: reject a request whose `A2A-Version` service parameter names an
+/// unsupported major version. §3.6.1/§3.6.2 both require an absent value
+/// to be interpreted as "0.3", not as "whatever this interface happens to
+/// serve" -- so it's rejected here exactly like any other unsupported
+/// version, rather than silently processed as this build's version.
+///
+/// Every protocol binding calls this before dispatching a request, since
+/// §3.6.2 applies to each interface the agent exposes.
+pub fn check_a2a_version(params: &ServiceParams) -> Result<(), A2AError> {
+ let requested = params
+ .get("a2a-version")
+ .and_then(|v| v.first())
+ .map(String::as_str)
+ .unwrap_or("0.3");
+ match parse_major_version(requested) {
+ Some(SUPPORTED_MAJOR_VERSION) => Ok(()),
+ _ => Err(A2AError::version_not_supported(requested)),
+ }
+}
+
/// Build [`ServiceParams`] from an axum [`HeaderMap`].
///
/// Header names are normalized to lowercase (axum does this for us), values
diff --git a/a2a-server/src/rest.rs b/a2a-server/src/rest.rs
index 6303ab10..7363a948 100644
--- a/a2a-server/src/rest.rs
+++ b/a2a-server/src/rest.rs
@@ -7,9 +7,10 @@ use a2a::*;
use a2a_pb::protojson_conv::{self, ProtoJsonPayload};
use axum::{
Json,
- extract::{Path, Query, State},
+ extract::{Path, Query, Request, State},
http::{HeaderMap, HeaderValue, StatusCode, header},
- response::IntoResponse,
+ middleware::Next,
+ response::{IntoResponse, Response},
};
use chrono::{DateTime, Utc};
use futures::{StreamExt, stream::BoxStream};
@@ -18,7 +19,7 @@ use serde_json::Value;
use std::collections::HashMap;
use crate::handler::RequestHandler;
-use crate::middleware::{ServiceParams, extract_service_params};
+use crate::middleware::{ServiceParams, check_a2a_version, extract_service_params};
use crate::sse;
const REST_SEND_MESSAGE_PATH: &str = "/message:send";
@@ -116,12 +117,36 @@ pub fn rest_router(handler: Arc) -> axum::Router {
REST_EXTENDED_AGENT_CARD_LEGACY_PATH,
axum::routing::get(handle_get_extended_agent_card::),
)
+ .route_layer(axum::middleware::from_fn(validate_protocol_version))
.layer(axum::extract::DefaultBodyLimit::max(
crate::jsonrpc::MAX_REQUEST_BODY_BYTES,
))
.with_state(state)
}
+/// §3.6.2 for every REST operation, ahead of any handler. §3.6.1 lets a
+/// client send `A2A-Version` as a query parameter instead of a header, so
+/// the query form is honored when the header is absent.
+async fn validate_protocol_version(request: Request, next: Next) -> Response {
+ let mut params = extract_service_params(request.headers());
+ if !params.contains_key("a2a-version") {
+ let from_query = Query::>::try_from_uri(request.uri())
+ .ok()
+ .and_then(|Query(query)| {
+ query
+ .into_iter()
+ .find(|(name, _)| name.eq_ignore_ascii_case(SVC_PARAM_VERSION))
+ });
+ if let Some((_, version)) = from_query {
+ params.insert("a2a-version".to_owned(), vec![version]);
+ }
+ }
+ match check_a2a_version(¶ms) {
+ Ok(()) => next.run(request).await,
+ Err(error) => rest_error_response(error),
+ }
+}
+
async fn handle_send_message(
State(state): State>,
headers: HeaderMap,
@@ -616,6 +641,7 @@ mod tests {
}
});
let req = Request::builder()
+ .header("a2a-version", "1.0")
.uri(REST_SEND_MESSAGE_PATH)
.method("POST")
.header("content-type", "application/json")
@@ -638,6 +664,7 @@ mod tests {
}
});
let req = Request::builder()
+ .header("a2a-version", "1.0")
.uri(REST_SEND_MESSAGE_PATH)
.method("POST")
.header("content-type", "application/json")
@@ -681,6 +708,7 @@ mod tests {
}
});
let req = Request::builder()
+ .header("a2a-version", "1.0")
.uri(REST_SEND_MESSAGE_LEGACY_PATH)
.method("POST")
.header("content-type", "application/json")
@@ -694,6 +722,7 @@ mod tests {
async fn test_get_task_not_found() {
let app = make_app();
let req = Request::builder()
+ .header("a2a-version", "1.0")
.uri("/tasks/nonexistent")
.method("GET")
.body(Body::empty())
@@ -706,6 +735,7 @@ mod tests {
async fn test_list_tasks_empty() {
let app = make_app();
let req = Request::builder()
+ .header("a2a-version", "1.0")
.uri("/tasks")
.method("GET")
.body(Body::empty())
@@ -723,6 +753,7 @@ mod tests {
async fn test_cancel_task_not_found() {
let app = make_app();
let req = Request::builder()
+ .header("a2a-version", "1.0")
.uri("/tasks/nonexistent:cancel")
.method("POST")
.header("content-type", "application/json")
@@ -739,6 +770,7 @@ mod tests {
"url": "http://example.com/callback"
});
let req = Request::builder()
+ .header("a2a-version", "1.0")
.uri("/tasks/t1/pushNotificationConfigs")
.method("POST")
.header("content-type", "application/json")
@@ -756,6 +788,7 @@ mod tests {
"url": "http://example.com/callback"
});
let req = Request::builder()
+ .header("a2a-version", "1.0")
.uri("/tasks/t1/pushNotificationConfigs")
.method("POST")
.header("content-type", "application/json")
@@ -779,6 +812,7 @@ mod tests {
"url": "http://example.com/callback"
});
let req = Request::builder()
+ .header("a2a-version", "1.0")
.uri("/tasks/t1/pushNotificationConfigs")
.method("POST")
.header("content-type", "application/json")
@@ -801,6 +835,7 @@ mod tests {
"url": "http://example.com/callback"
});
let req = Request::builder()
+ .header("a2a-version", "1.0")
.uri("/tasks/t1/pushNotificationConfigs")
.method("POST")
.header("content-type", "application/json")
@@ -814,6 +849,7 @@ mod tests {
async fn test_get_extended_agent_card() {
let app = make_app();
let req = Request::builder()
+ .header("a2a-version", "1.0")
.uri(REST_EXTENDED_AGENT_CARD_PATH)
.method("GET")
.body(Body::empty())
@@ -1003,6 +1039,7 @@ mod tests {
async fn test_subscribe_to_task_not_found() {
let app = make_app();
let req = Request::builder()
+ .header("a2a-version", "1.0")
.uri("/tasks/nonexistent:subscribe")
.method("GET")
.body(Body::empty())
@@ -1022,6 +1059,7 @@ mod tests {
}
});
let req = Request::builder()
+ .header("a2a-version", "1.0")
.uri(REST_STREAM_MESSAGE_PATH)
.method("POST")
.header("content-type", "application/json")
@@ -1036,6 +1074,7 @@ mod tests {
async fn test_get_push_config_not_found() {
let app = make_app();
let req = Request::builder()
+ .header("a2a-version", "1.0")
.uri("/tasks/t1/pushNotificationConfigs/cfg1")
.method("GET")
.body(Body::empty())
@@ -1049,6 +1088,7 @@ mod tests {
async fn test_list_push_configs() {
let app = make_push_app();
let req = Request::builder()
+ .header("a2a-version", "1.0")
.uri("/tasks/t1/pushNotificationConfigs")
.method("GET")
.body(Body::empty())
@@ -1065,6 +1105,7 @@ mod tests {
async fn test_delete_push_config() {
let app = make_app();
let req = Request::builder()
+ .header("a2a-version", "1.0")
.uri("/tasks/t1/pushNotificationConfigs/cfg1")
.method("DELETE")
.body(Body::empty())
@@ -1081,6 +1122,7 @@ mod tests {
"url": "http://example.com/callback"
});
let create_req = Request::builder()
+ .header("a2a-version", "1.0")
.uri("/tasks/t1/pushNotificationConfigs")
.method("POST")
.header("content-type", "application/json")
@@ -1090,6 +1132,7 @@ mod tests {
assert_eq!(create_resp.status(), StatusCode::OK);
let delete_req = Request::builder()
+ .header("a2a-version", "1.0")
.uri("/tasks/t1/pushNotificationConfigs/cfg1")
.method("DELETE")
.body(Body::empty())
@@ -1098,6 +1141,7 @@ mod tests {
assert_eq!(delete_resp.status(), StatusCode::OK);
let list_req = Request::builder()
+ .header("a2a-version", "1.0")
.uri("/tasks/t1/pushNotificationConfigs")
.method("GET")
.body(Body::empty())
@@ -1114,6 +1158,7 @@ mod tests {
async fn test_list_tasks_with_query_params() {
let app = make_app();
let req = Request::builder()
+ .header("a2a-version", "1.0")
.uri("/tasks?contextId=c1&pageSize=5&pageToken=0&historyLength=3&includeArtifacts=true&statusTimestampAfter=2025-01-01T00:00:00Z")
.method("GET")
.body(Body::empty())
@@ -1126,6 +1171,7 @@ mod tests {
async fn test_list_tasks_invalid_status_returns_bad_request() {
let app = make_app();
let req = Request::builder()
+ .header("a2a-version", "1.0")
.uri("/tasks?status=invalid")
.method("GET")
.body(Body::empty())
@@ -1150,6 +1196,7 @@ mod tests {
}
});
let req = Request::builder()
+ .header("a2a-version", "1.0")
.uri(REST_SEND_MESSAGE_PATH)
.method("POST")
.header("content-type", "application/json")
@@ -1181,6 +1228,7 @@ mod tests {
}
});
let req = Request::builder()
+ .header("a2a-version", "1.0")
.uri(REST_STREAM_MESSAGE_PATH)
.method("POST")
.header("content-type", "application/json")
@@ -1205,6 +1253,7 @@ mod tests {
let (handler, captured) = CapturingHandler::new();
let app = rest_router(handler);
let req = Request::builder()
+ .header("a2a-version", "1.0")
.uri("/tasks/some-id")
.method("GET")
.header("authorization", "Bearer get-task-token")
@@ -1226,6 +1275,7 @@ mod tests {
let (handler, captured) = CapturingHandler::new();
let app = rest_router(handler);
let req = Request::builder()
+ .header("a2a-version", "1.0")
.uri("/tasks")
.method("GET")
.header("authorization", "Bearer list-tasks-token")
@@ -1245,6 +1295,7 @@ mod tests {
let (handler, captured) = CapturingHandler::new();
let app = rest_router(handler);
let req = Request::builder()
+ .header("a2a-version", "1.0")
.uri("/tasks/some-id:cancel")
.method("POST")
.header("authorization", "Bearer cancel-token")
@@ -1265,6 +1316,7 @@ mod tests {
let (handler, captured) = CapturingHandler::new();
let app = rest_router(handler);
let req = Request::builder()
+ .header("a2a-version", "1.0")
.uri("/tasks/some-id/cancel")
.method("POST")
.header("authorization", "Bearer cancel-legacy-token")
@@ -1288,6 +1340,7 @@ mod tests {
"url": "http://example.com/callback"
});
let req = Request::builder()
+ .header("a2a-version", "1.0")
.uri("/tasks/t1/pushNotificationConfigs")
.method("POST")
.header("content-type", "application/json")
@@ -1308,6 +1361,7 @@ mod tests {
let (handler, captured) = CapturingHandler::new();
let app = rest_router(handler);
let req = Request::builder()
+ .header("a2a-version", "1.0")
.uri("/tasks/t1/pushNotificationConfigs")
.method("GET")
.header("authorization", "Bearer push-list-token")
@@ -1327,6 +1381,7 @@ mod tests {
let (handler, captured) = CapturingHandler::new();
let app = rest_router(handler);
let req = Request::builder()
+ .header("a2a-version", "1.0")
.uri("/tasks/t1/pushNotificationConfigs/cfg1")
.method("GET")
.header("authorization", "Bearer push-get-token")
@@ -1346,6 +1401,7 @@ mod tests {
let (handler, captured) = CapturingHandler::new();
let app = rest_router(handler);
let req = Request::builder()
+ .header("a2a-version", "1.0")
.uri("/tasks/t1/pushNotificationConfigs/cfg1")
.method("DELETE")
.header("authorization", "Bearer push-delete-token")
@@ -1365,6 +1421,7 @@ mod tests {
let (handler, captured) = CapturingHandler::new();
let app = rest_router(handler);
let req = Request::builder()
+ .header("a2a-version", "1.0")
.uri(REST_EXTENDED_AGENT_CARD_PATH)
.method("GET")
.header("authorization", "Bearer card-token")
@@ -1384,6 +1441,7 @@ mod tests {
let (handler, captured) = CapturingHandler::new();
let app = rest_router(handler);
let req = Request::builder()
+ .header("a2a-version", "1.0")
.uri("/tasks/some-id:subscribe")
.method("GET")
.header("authorization", "Bearer subscribe-token")
@@ -1405,6 +1463,7 @@ mod tests {
let (handler, captured) = CapturingHandler::new();
let app = rest_router(handler);
let req = Request::builder()
+ .header("a2a-version", "1.0")
.uri("/tasks/some-id/subscribe")
.method("GET")
.header("authorization", "Bearer subscribe-legacy-token")
@@ -1433,6 +1492,7 @@ mod tests {
}
});
let req = Request::builder()
+ .header("a2a-version", "1.0")
.uri(REST_SEND_MESSAGE_PATH)
.method("POST")
.header("content-type", "application/json")
@@ -1446,6 +1506,7 @@ mod tests {
let app = make_app();
let req = Request::builder()
+ .header("a2a-version", "1.0")
.uri(format!("/tasks/{}?historyLength=5", task_id))
.method("GET")
.body(Body::empty())
@@ -1463,6 +1524,7 @@ mod tests {
let app = make_app();
let oversized = Body::from("x".repeat(crate::jsonrpc::MAX_REQUEST_BODY_BYTES + 1));
let req = Request::builder()
+ .header("a2a-version", "1.0")
.uri(REST_SEND_MESSAGE_PATH)
.method("POST")
.header("content-type", "application/json")
@@ -1472,4 +1534,65 @@ mod tests {
let resp = app.oneshot(req).await.unwrap();
assert_eq!(resp.status(), StatusCode::PAYLOAD_TOO_LARGE);
}
+
+ async fn send_message_with_version(uri: &str, version: Option<&str>) -> Response {
+ let body = serde_json::json!({
+ "message": {"messageId": "m1", "role": "ROLE_USER", "parts": [{"text": "hi"}]}
+ });
+ let mut req = Request::builder()
+ .uri(uri)
+ .method("POST")
+ .header("content-type", "application/json");
+ if let Some(version) = version {
+ req = req.header("a2a-version", version);
+ }
+ let req = req.body(Body::from(body.to_string())).unwrap();
+ make_app().oneshot(req).await.unwrap()
+ }
+
+ async fn assert_version_not_supported(resp: Response) {
+ assert_eq!(resp.status(), StatusCode::BAD_REQUEST);
+ let body = resp.into_body().collect().await.unwrap().to_bytes();
+ let payload: serde_json::Value = serde_json::from_slice(&body).unwrap();
+ assert_eq!(
+ payload["error"]["status"], "FAILED_PRECONDITION",
+ "{payload}"
+ );
+ assert_eq!(
+ payload["error"]["details"][0]["reason"], "VERSION_NOT_SUPPORTED",
+ "{payload}"
+ );
+ }
+
+ #[tokio::test]
+ async fn test_unsupported_a2a_version_is_rejected() {
+ // §3.6.2, §6.4: same rejection as JSON-RPC, in REST's error shape.
+ let resp = send_message_with_version(REST_SEND_MESSAGE_PATH, Some("99.0")).await;
+ assert_version_not_supported(resp).await;
+ }
+
+ #[tokio::test]
+ async fn test_missing_a2a_version_is_rejected() {
+ // §3.6.2: an absent A2A-Version is "0.3", which this server does not
+ // implement -- on every route, not only SendMessage.
+ let resp = send_message_with_version(REST_SEND_MESSAGE_PATH, None).await;
+ assert_version_not_supported(resp).await;
+
+ let req = Request::builder()
+ .uri("/tasks/t1")
+ .body(Body::empty())
+ .unwrap();
+ assert_version_not_supported(make_app().oneshot(req).await.unwrap()).await;
+ }
+
+ #[tokio::test]
+ async fn test_a2a_version_query_parameter_is_accepted() {
+ // §3.6.1: a client MAY send the version as a request parameter.
+ let uri = format!("{REST_SEND_MESSAGE_PATH}?A2A-Version=1.0");
+ let resp = send_message_with_version(&uri, None).await;
+ assert_eq!(resp.status(), StatusCode::OK);
+
+ let uri = format!("{REST_SEND_MESSAGE_PATH}?A2A-Version=99.0");
+ assert_version_not_supported(send_message_with_version(&uri, None).await).await;
+ }
}
diff --git a/examples/tests/transports_e2e.rs b/examples/tests/transports_e2e.rs
index bd019c55..92f4e34f 100644
--- a/examples/tests/transports_e2e.rs
+++ b/examples/tests/transports_e2e.rs
@@ -431,9 +431,9 @@ async fn recv_push(receiver: &mut mpsc::UnboundedReceiver) -> Capt
.unwrap()
}
-/// A2A-Version header a real client sends. Only JSON-RPC checks it
-/// (§3.6.2); the REST tests use bare `ServiceParams::new()`.
-fn jsonrpc_service_params() -> ServiceParams {
+/// A2A-Version header a real client sends (§3.6.1); every binding rejects
+/// a request without one (§3.6.2).
+fn versioned_params() -> ServiceParams {
let mut params = ServiceParams::new();
params.insert(SVC_PARAM_VERSION.to_string(), vec![VERSION.to_string()]);
params
@@ -454,13 +454,13 @@ async fn rest_transport_end_to_end() {
let transport = RestTransport::new(Client::new(), format!("{base_url}/rest"));
let send_resp = transport
- .send_message(&ServiceParams::new(), &send_message_request())
+ .send_message(&versioned_params(), &send_message_request())
.await;
assert!(matches!(send_resp.unwrap(), SendMessageResponse::Task(_)));
let task = transport
.get_task(
- &ServiceParams::new(),
+ &versioned_params(),
&GetTaskRequest {
id: "task-1".to_string(),
history_length: Some(2),
@@ -473,7 +473,7 @@ async fn rest_transport_end_to_end() {
let not_found = transport
.get_task(
- &ServiceParams::new(),
+ &versioned_params(),
&GetTaskRequest {
id: "missing".to_string(),
history_length: None,
@@ -486,7 +486,7 @@ async fn rest_transport_end_to_end() {
let list = transport
.list_tasks(
- &ServiceParams::new(),
+ &versioned_params(),
&ListTasksRequest {
context_id: Some("ctx-1".to_string()),
status: Some(TaskState::Completed),
@@ -504,7 +504,7 @@ async fn rest_transport_end_to_end() {
let canceled = transport
.cancel_task(
- &ServiceParams::new(),
+ &versioned_params(),
&CancelTaskRequest {
id: "task-1".to_string(),
metadata: None,
@@ -517,7 +517,7 @@ async fn rest_transport_end_to_end() {
let cancel_missing = transport
.cancel_task(
- &ServiceParams::new(),
+ &versioned_params(),
&CancelTaskRequest {
id: "missing".to_string(),
metadata: None,
@@ -530,7 +530,7 @@ async fn rest_transport_end_to_end() {
let subscribed = transport
.subscribe_to_task(
- &ServiceParams::new(),
+ &versioned_params(),
&SubscribeToTaskRequest {
id: "task-1".to_string(),
tenant: None,
@@ -542,14 +542,14 @@ async fn rest_transport_end_to_end() {
assert_eq!(events.len(), 1);
let created = transport
- .create_push_config(&ServiceParams::new(), &sample_push_config("cfg-1"))
+ .create_push_config(&versioned_params(), &sample_push_config("cfg-1"))
.await
.unwrap();
assert_eq!(created.task_id, "task-1");
let created_missing = transport
.create_push_config(
- &ServiceParams::new(),
+ &versioned_params(),
&TaskPushNotificationConfig {
task_id: "missing".to_string(),
..sample_push_config("cfg-1")
@@ -561,7 +561,7 @@ async fn rest_transport_end_to_end() {
let fetched = transport
.get_push_config(
- &ServiceParams::new(),
+ &versioned_params(),
&GetTaskPushNotificationConfigRequest {
task_id: "task-1".to_string(),
id: "cfg-1".to_string(),
@@ -574,7 +574,7 @@ async fn rest_transport_end_to_end() {
let fetched_missing = transport
.get_push_config(
- &ServiceParams::new(),
+ &versioned_params(),
&GetTaskPushNotificationConfigRequest {
task_id: "task-1".to_string(),
id: "missing".to_string(),
@@ -587,7 +587,7 @@ async fn rest_transport_end_to_end() {
let configs = transport
.list_push_configs(
- &ServiceParams::new(),
+ &versioned_params(),
&ListTaskPushNotificationConfigsRequest {
task_id: "task-1".to_string(),
page_size: Some(5),
@@ -601,7 +601,7 @@ async fn rest_transport_end_to_end() {
transport
.delete_push_config(
- &ServiceParams::new(),
+ &versioned_params(),
&DeleteTaskPushNotificationConfigRequest {
task_id: "task-1".to_string(),
id: "cfg-1".to_string(),
@@ -613,7 +613,7 @@ async fn rest_transport_end_to_end() {
let delete_missing = transport
.delete_push_config(
- &ServiceParams::new(),
+ &versioned_params(),
&DeleteTaskPushNotificationConfigRequest {
task_id: "task-1".to_string(),
id: "missing".to_string(),
@@ -645,12 +645,12 @@ async fn jsonrpc_transport_end_to_end() {
let transport = JsonRpcTransport::new(Client::new(), format!("{base_url}/rpc"));
let send_resp = transport
- .send_message(&jsonrpc_service_params(), &send_message_request())
+ .send_message(&versioned_params(), &send_message_request())
.await;
assert!(matches!(send_resp.unwrap(), SendMessageResponse::Task(_)));
let stream = transport
- .send_streaming_message(&jsonrpc_service_params(), &send_message_request())
+ .send_streaming_message(&versioned_params(), &send_message_request())
.await
.unwrap();
let items: Vec<_> = stream.collect().await;
@@ -658,7 +658,7 @@ async fn jsonrpc_transport_end_to_end() {
let task = transport
.get_task(
- &jsonrpc_service_params(),
+ &versioned_params(),
&GetTaskRequest {
id: "task-1".to_string(),
history_length: Some(2),
@@ -671,7 +671,7 @@ async fn jsonrpc_transport_end_to_end() {
let not_found = transport
.get_task(
- &jsonrpc_service_params(),
+ &versioned_params(),
&GetTaskRequest {
id: "missing".to_string(),
history_length: None,
@@ -684,7 +684,7 @@ async fn jsonrpc_transport_end_to_end() {
let list = transport
.list_tasks(
- &jsonrpc_service_params(),
+ &versioned_params(),
&ListTasksRequest {
context_id: Some("ctx-1".to_string()),
status: Some(TaskState::Completed),
@@ -702,7 +702,7 @@ async fn jsonrpc_transport_end_to_end() {
let canceled = transport
.cancel_task(
- &jsonrpc_service_params(),
+ &versioned_params(),
&CancelTaskRequest {
id: "task-1".to_string(),
metadata: None,
@@ -715,7 +715,7 @@ async fn jsonrpc_transport_end_to_end() {
let cancel_missing = transport
.cancel_task(
- &jsonrpc_service_params(),
+ &versioned_params(),
&CancelTaskRequest {
id: "missing".to_string(),
metadata: None,
@@ -728,7 +728,7 @@ async fn jsonrpc_transport_end_to_end() {
let subscribed = transport
.subscribe_to_task(
- &jsonrpc_service_params(),
+ &versioned_params(),
&SubscribeToTaskRequest {
id: "task-1".to_string(),
tenant: None,
@@ -740,14 +740,14 @@ async fn jsonrpc_transport_end_to_end() {
assert_eq!(events.len(), 1);
let created = transport
- .create_push_config(&jsonrpc_service_params(), &sample_push_config("cfg-1"))
+ .create_push_config(&versioned_params(), &sample_push_config("cfg-1"))
.await
.unwrap();
assert_eq!(created.task_id, "task-1");
let created_missing = transport
.create_push_config(
- &jsonrpc_service_params(),
+ &versioned_params(),
&TaskPushNotificationConfig {
task_id: "missing".to_string(),
..sample_push_config("cfg-1")
@@ -759,7 +759,7 @@ async fn jsonrpc_transport_end_to_end() {
let fetched = transport
.get_push_config(
- &jsonrpc_service_params(),
+ &versioned_params(),
&GetTaskPushNotificationConfigRequest {
task_id: "task-1".to_string(),
id: "cfg-1".to_string(),
@@ -772,7 +772,7 @@ async fn jsonrpc_transport_end_to_end() {
let fetched_missing = transport
.get_push_config(
- &jsonrpc_service_params(),
+ &versioned_params(),
&GetTaskPushNotificationConfigRequest {
task_id: "task-1".to_string(),
id: "missing".to_string(),
@@ -785,7 +785,7 @@ async fn jsonrpc_transport_end_to_end() {
let listed = transport
.list_push_configs(
- &jsonrpc_service_params(),
+ &versioned_params(),
&ListTaskPushNotificationConfigsRequest {
task_id: "task-1".to_string(),
page_size: Some(5),
@@ -799,7 +799,7 @@ async fn jsonrpc_transport_end_to_end() {
transport
.delete_push_config(
- &jsonrpc_service_params(),
+ &versioned_params(),
&DeleteTaskPushNotificationConfigRequest {
task_id: "task-1".to_string(),
id: "cfg-1".to_string(),
@@ -811,7 +811,7 @@ async fn jsonrpc_transport_end_to_end() {
let delete_missing = transport
.delete_push_config(
- &jsonrpc_service_params(),
+ &versioned_params(),
&DeleteTaskPushNotificationConfigRequest {
task_id: "task-1".to_string(),
id: "missing".to_string(),
@@ -824,7 +824,7 @@ async fn jsonrpc_transport_end_to_end() {
let card = transport
.get_extended_agent_card(
- &jsonrpc_service_params(),
+ &versioned_params(),
&GetExtendedAgentCardRequest { tenant: None },
)
.await
@@ -842,7 +842,7 @@ async fn rest_transport_push_delivery_end_to_end() {
transport
.create_push_config(
- &ServiceParams::new(),
+ &versioned_params(),
&TaskPushNotificationConfig {
task_id: "task-rest-push".to_string(),
url: webhook_url,
@@ -863,7 +863,7 @@ async fn rest_transport_push_delivery_end_to_end() {
request.message.context_id = Some("ctx-rest-push".to_string());
let response = transport
- .send_message(&ServiceParams::new(), &request)
+ .send_message(&versioned_params(), &request)
.await
.unwrap();
assert!(matches!(response, SendMessageResponse::Task(_)));
@@ -927,14 +927,14 @@ async fn jsonrpc_transport_push_delivery_end_to_end() {
});
let response = transport
- .send_message(&jsonrpc_service_params(), &request)
+ .send_message(&versioned_params(), &request)
.await
.unwrap();
assert!(matches!(response, SendMessageResponse::Task(_)));
let saved = transport
.get_push_config(
- &jsonrpc_service_params(),
+ &versioned_params(),
&GetTaskPushNotificationConfigRequest {
task_id: "task-rpc-push".to_string(),
id: "cfg-rpc".to_string(),
From 08871caeb407b2d5e512ee6fb809282a7954719c Mon Sep 17 00:00:00 2001
From: gulldan <5641375+gulldan@users.noreply.github.com>
Date: Thu, 29 Oct 2026 14:30:05 +0300
Subject: [PATCH 06/14] fix(server): let SubscribeToTask follow a task that
awaits input
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
`subscribe_to_task` resubscribed only to a task whose execution was
still registered. An execution that ends in an interrupted state
(INPUT_REQUIRED, AUTH_REQUIRED) is unregistered as soon as the executor
returns, and the task-store fallback turned only a terminal stored task
into UnsupportedOperationError, so a stored task that waits for input
was reported as TaskNotFoundError. A2A §3.1.6 allows subscribing to
any non-terminal task, and the stream must open with the task as it
stands.
A subscription that finds no registered execution is now registered
with the execution manager, under its lock and before the store is
read, so an execution that registers from then on attaches it: `start`
subscribes every waiter before the executor runs, so none of that
turn's events is missed, and from there the stream is an ordinary
resubscription. The stream opens with the stored task and ends where
the execution it attached to ends. A missing task is still
TaskNotFoundError, a terminal one still UnsupportedOperationError, and
a waiter dropped first unregisters itself.
Tested with handler unit tests (a turn that asks for input and one that
completes; two subscribers polled only after the next turn ran; a
dropped subscription; the unchanged errors), `just ci` on Linux, and
the official TCK against an agent built on the patched crates, where
STREAM-SUB-001/002 and STREAM-ORDER-002..004 now pass instead of being
skipped.
Fixes: #393
Co-Authored-By: Claude
Signed-off-by: gulldan <5641375+gulldan@users.noreply.github.com>
---
a2a-server/src/handler.rs | 319 +++++++++++++++++++++++++++++++++++---
1 file changed, 296 insertions(+), 23 deletions(-)
diff --git a/a2a-server/src/handler.rs b/a2a-server/src/handler.rs
index def3e899..60f02874 100644
--- a/a2a-server/src/handler.rs
+++ b/a2a-server/src/handler.rs
@@ -3,9 +3,15 @@
// SPDX-License-Identifier: Apache-2.0
use a2a::*;
use async_trait::async_trait;
-use futures::{StreamExt, stream::BoxStream};
-use std::{collections::HashMap, sync::Arc};
-use tokio::sync::{RwLock, broadcast};
+use futures::{
+ StreamExt,
+ stream::{self, BoxStream},
+};
+use std::{
+ collections::HashMap,
+ sync::{Arc, Mutex, MutexGuard, PoisonError},
+};
+use tokio::sync::{RwLock, broadcast, oneshot};
use crate::middleware::ServiceParams;
use crate::pagination::resolve_page_size;
@@ -13,6 +19,10 @@ use crate::task_store::apply_history_length;
const EXECUTION_BUFFER_CAPACITY: usize = 32;
+/// What a subscription attaches to: the events to come, the task as of the
+/// last event already published, and that event's sequence.
+type Resubscription = (broadcast::Receiver, Option, u64);
+
#[derive(Clone)]
struct ExecutionEvent {
sequence: u64,
@@ -46,7 +56,7 @@ impl ActiveExecution {
self.sender.subscribe()
}
- async fn resubscribe(&self) -> (broadcast::Receiver, Option, u64) {
+ async fn resubscribe(&self) -> Resubscription {
let receiver = self.sender.subscribe();
let state = self.state.read().await;
(receiver, state.snapshot_task.clone(), state.sequence)
@@ -91,9 +101,17 @@ impl ActiveExecution {
#[derive(Default)]
struct ExecutionManager {
executions: RwLock>>,
+ /// Subscriptions to tasks with no registered execution, which `start`
+ /// attaches to the next one. Taken under `executions` by `start` and
+ /// `subscribe`, alone by `Waiter::drop`, never across an await.
+ waiting: Mutex>>>,
}
impl ExecutionManager {
+ fn waiting(&self) -> MutexGuard<'_, HashMap>>> {
+ self.waiting.lock().unwrap_or_else(PoisonError::into_inner)
+ }
+
async fn start(&self, task: Task) -> Result, A2AError> {
let mut executions = self.executions.write().await;
if executions.contains_key(&task.id) {
@@ -105,6 +123,11 @@ impl ExecutionManager {
let active = ActiveExecution::new(task.clone());
executions.insert(task.id.clone(), active.clone());
+ // Subscribed before the executor runs, so they miss none of its events.
+ let waiting = self.waiting().remove(&task.id).unwrap_or_default();
+ for waiter in waiting {
+ let _ = waiter.send((active.subscribe(), Some(task.clone()), 0));
+ }
Ok(active)
}
@@ -113,13 +136,30 @@ impl ExecutionManager {
executions.get(task_id).cloned()
}
- async fn resubscribe(
- &self,
- task_id: &str,
- ) -> Option<(broadcast::Receiver, Option, u64)> {
- let active = self.get(task_id).await?;
- let (receiver, snapshot_task, sequence) = active.resubscribe().await;
- Some((receiver, snapshot_task, sequence))
+ /// Subscribes to the task's registered execution or, when there is none,
+ /// to the next one `start` registers. Decided under the registry lock, so
+ /// an execution registering meanwhile is either found here or finds the
+ /// waiter.
+ async fn subscribe(self: &Arc, task_id: &str) -> Waiter {
+ let (sender, receiver) = oneshot::channel();
+ let executions = self.executions.read().await;
+ match executions.get(task_id) {
+ Some(active) => {
+ let _ = sender.send(active.resubscribe().await);
+ }
+ None => {
+ self.waiting()
+ .entry(task_id.to_owned())
+ .or_default()
+ .push(sender);
+ }
+ }
+ drop(executions);
+ Waiter {
+ manager: Arc::clone(self),
+ task_id: task_id.to_owned(),
+ attached: Some(receiver),
+ }
}
async fn finish(&self, task_id: &str, active: &Arc) {
@@ -133,6 +173,48 @@ impl ExecutionManager {
}
}
+/// A subscription that `ExecutionManager::start` attaches to the task's next
+/// execution. Dropped first, it leaves nothing behind in the registry.
+struct Waiter {
+ manager: Arc,
+ task_id: TaskId,
+ attached: Option>,
+}
+
+impl Waiter {
+ /// The execution attached so far, if any.
+ fn attached(&mut self) -> Option {
+ self.attached.as_mut()?.try_recv().ok()
+ }
+
+ /// The events of the execution once attached; none if the handler goes
+ /// away first.
+ fn into_stream(mut self) -> BoxStream<'static, Result> {
+ stream::once(async move { self.attached.as_mut()?.await.ok() })
+ .flat_map(|attached| match attached {
+ Some((receiver, snapshot_task, sequence)) => {
+ subscription_stream(receiver, snapshot_task, sequence)
+ }
+ None => stream::empty().boxed(),
+ })
+ .boxed()
+ }
+}
+
+impl Drop for Waiter {
+ fn drop(&mut self) {
+ // Closing the receiver is what marks this waiter's own sender closed.
+ self.attached = None;
+ let mut waiting = self.manager.waiting();
+ if let Some(waiters) = waiting.get_mut(&self.task_id) {
+ waiters.retain(|waiter| !waiter.is_closed());
+ if waiters.is_empty() {
+ waiting.remove(&self.task_id);
+ }
+ }
+ }
+}
+
struct ExecutionRuntime {
executor: Arc,
task_store: Arc,
@@ -1052,9 +1134,10 @@ impl RequestHandler for DefaultRequestHandler {
) -> Result>, A2AError> {
self.authorize(params, Some(&req.id))?;
self.require_streaming()?;
- if let Some((receiver, snapshot_task, sequence)) =
- self.execution_manager.resubscribe(&req.id).await
- {
+ // Registered before the store is read: an execution that starts from
+ // here on attaches this subscription itself, so nothing is missed.
+ let mut waiter = self.execution_manager.subscribe(&req.id).await;
+ if let Some((receiver, snapshot_task, sequence)) = waiter.attached() {
return Ok(subscription_stream(receiver, snapshot_task, sequence));
}
@@ -1062,15 +1145,26 @@ impl RequestHandler for DefaultRequestHandler {
// execution is cleaned up, so it doesn't by itself mean the task
// never existed -- check the store to tell the two apart before
// reporting TaskNotFoundError.
- if let Some(task) = self.task_store.get(&req.id).await? {
- if task.status.state.is_terminal() {
- return Err(A2AError::unsupported_operation(format!(
- "task {} has already reached a terminal state",
- req.id
- )));
- }
+ let task = self.load_task(&req.id).await?;
+ // An execution that started while the store was read may have moved
+ // the task on already; the waiter has everything it published.
+ if let Some((receiver, snapshot_task, sequence)) = waiter.attached() {
+ return Ok(subscription_stream(receiver, snapshot_task, sequence));
+ }
+ if task.status.state.is_terminal() {
+ return Err(A2AError::unsupported_operation(format!(
+ "task {} has already reached a terminal state",
+ req.id
+ )));
}
- Err(A2AError::task_not_found(&req.id))
+
+ // The task is between turns, in an interrupted state; §3.1.6 allows
+ // subscribing to any non-terminal task. The stream opens with the
+ // task as stored, then follows the execution the next message starts
+ // to its end, as a resubscription would (TCK STREAM-SUB-002).
+ Ok(stream::once(async move { Ok(StreamResponse::Task(task)) })
+ .chain(waiter.into_stream())
+ .boxed())
}
async fn create_push_config(
@@ -1559,6 +1653,39 @@ mod tests {
}
}
+ /// Asks for input on the task's first turn and completes on the next.
+ struct InputRequiredExecutor;
+
+ impl crate::AgentExecutor for InputRequiredExecutor {
+ fn execute(
+ &self,
+ ctx: ExecutorContext,
+ ) -> BoxStream<'static, Result> {
+ let state = match ctx.stored_task.as_ref().map(|task| &task.status.state) {
+ Some(TaskState::InputRequired) => TaskState::Completed,
+ _ => TaskState::InputRequired,
+ };
+ let update = StreamResponse::StatusUpdate(TaskStatusUpdateEvent {
+ task_id: ctx.task_id,
+ context_id: ctx.context_id,
+ status: TaskStatus {
+ state,
+ message: None,
+ timestamp: None,
+ },
+ metadata: None,
+ });
+ Box::pin(stream::once(async move { Ok(update) }))
+ }
+
+ fn cancel(
+ &self,
+ _ctx: ExecutorContext,
+ ) -> BoxStream<'static, Result> {
+ Box::pin(stream::empty())
+ }
+ }
+
/// Pre-create a task so a message may legitimately reference it: A2A
/// §3.4.2 forbids client-provided taskIds for *creating* tasks.
async fn seed_task(handler: &DefaultRequestHandler, task_id: &str, context_id: &str) {
@@ -1615,6 +1742,33 @@ mod tests {
)
}
+ fn make_input_required_handler() -> DefaultRequestHandler {
+ DefaultRequestHandler::new(InputRequiredExecutor, InMemoryTaskStore::new())
+ }
+
+ /// A task whose first turn ended asking for input: stored, but with no
+ /// execution registered any more.
+ async fn task_awaiting_input(handler: &DefaultRequestHandler) -> Task {
+ let response = handler
+ .send_message(
+ &ServiceParams::new(),
+ SendMessageRequest {
+ message: make_message(),
+ configuration: None,
+ metadata: None,
+ tenant: None,
+ },
+ )
+ .await
+ .unwrap();
+ let SendMessageResponse::Task(task) = response else {
+ panic!("expected a task");
+ };
+ assert_eq!(task.status.state, TaskState::InputRequired);
+ assert!(handler.execution_manager.get(&task.id).await.is_none());
+ task
+ }
+
fn make_message() -> Message {
Message::new(Role::User, vec![Part::text("hello")])
}
@@ -2872,7 +3026,7 @@ mod tests {
}
#[tokio::test]
- async fn test_subscribe_requires_active_execution() {
+ async fn test_subscribe_to_an_unknown_task_is_not_found() {
let handler = make_handler();
let params = ServiceParams::new();
let req = SubscribeToTaskRequest {
@@ -2884,6 +3038,7 @@ mod tests {
Ok(_) => panic!("expected subscribe_to_task to fail"),
Err(error) => assert_eq!(error.code, error_code::TASK_NOT_FOUND),
}
+ assert!(handler.execution_manager.waiting().is_empty());
}
#[tokio::test]
@@ -2918,6 +3073,124 @@ mod tests {
Ok(_) => panic!("expected subscribe_to_task to fail"),
Err(error) => assert_eq!(error.code, error_code::UNSUPPORTED_OPERATION),
}
+ assert!(handler.execution_manager.waiting().is_empty());
+ }
+
+ #[tokio::test]
+ async fn test_subscribe_to_a_task_awaiting_input_opens_with_the_stored_task() {
+ let handler = make_input_required_handler();
+ let params = ServiceParams::new();
+ let task = task_awaiting_input(&handler).await;
+ let stored = handler
+ .get_task(
+ ¶ms,
+ GetTaskRequest {
+ id: task.id.clone(),
+ history_length: None,
+ tenant: None,
+ },
+ )
+ .await
+ .unwrap();
+ assert_eq!(stored.status.state, TaskState::InputRequired);
+
+ let mut subscription = handler
+ .subscribe_to_task(
+ ¶ms,
+ SubscribeToTaskRequest {
+ id: task.id.clone(),
+ tenant: None,
+ },
+ )
+ .await
+ .unwrap();
+ match subscription.next().await.unwrap().unwrap() {
+ StreamResponse::Task(first) => assert_eq!(first, stored),
+ other => panic!("expected the stored task first, got {other:?}"),
+ }
+ }
+
+ #[tokio::test]
+ async fn test_subscriptions_to_a_task_awaiting_input_follow_its_next_turn() {
+ let handler = make_input_required_handler();
+ let params = ServiceParams::new();
+ let task = task_awaiting_input(&handler).await;
+ let subscribe = || SubscribeToTaskRequest {
+ id: task.id.clone(),
+ tenant: None,
+ };
+ let first = handler
+ .subscribe_to_task(¶ms, subscribe())
+ .await
+ .unwrap();
+ let second = handler
+ .subscribe_to_task(¶ms, subscribe())
+ .await
+ .unwrap();
+
+ // The whole next turn runs before either stream is polled: what it
+ // publishes must still reach both.
+ let mut follow_up = make_message();
+ follow_up.task_id = Some(task.id.clone());
+ let response = handler
+ .send_message(
+ ¶ms,
+ SendMessageRequest {
+ message: follow_up,
+ configuration: None,
+ metadata: None,
+ tenant: None,
+ },
+ )
+ .await
+ .unwrap();
+ assert!(matches!(
+ response,
+ SendMessageResponse::Task(task) if task.status.state == TaskState::Completed
+ ));
+
+ let states = |events: Vec>| {
+ events
+ .into_iter()
+ .map(|event| match event.unwrap() {
+ StreamResponse::Task(task) => task.status.state,
+ StreamResponse::StatusUpdate(update) => update.status.state,
+ other => panic!("unexpected event {other:?}"),
+ })
+ .collect::>()
+ };
+ // The stored task, the task as the turn found it, then the turn.
+ let expected = [
+ TaskState::InputRequired,
+ TaskState::InputRequired,
+ TaskState::Completed,
+ ];
+ assert_eq!(states(first.collect().await), expected);
+ assert_eq!(states(second.collect().await), expected);
+
+ // Over: a new subscription is refused as for any finished task.
+ let result = handler.subscribe_to_task(¶ms, subscribe()).await;
+ assert!(matches!(result, Err(error) if error.code == error_code::UNSUPPORTED_OPERATION));
+ }
+
+ #[tokio::test]
+ async fn test_a_dropped_subscription_to_a_task_awaiting_input_unregisters() {
+ let handler = make_input_required_handler();
+ let params = ServiceParams::new();
+ let task = task_awaiting_input(&handler).await;
+ let subscription = handler
+ .subscribe_to_task(
+ ¶ms,
+ SubscribeToTaskRequest {
+ id: task.id.clone(),
+ tenant: None,
+ },
+ )
+ .await
+ .unwrap();
+ assert_eq!(handler.execution_manager.waiting().len(), 1);
+ drop(subscription);
+ assert!(handler.execution_manager.waiting().is_empty());
}
#[tokio::test]
From f0184acf3fc7ec694f506bf4b0b2ecc98d9026c4 Mon Sep 17 00:00:00 2001
From: gulldan <5641375+gulldan@users.noreply.github.com>
Date: Sun, 1 Nov 2026 10:02:19 +0300
Subject: [PATCH 07/14] fix(server): end a waiting subscription when its task
is canceled
A subscription to a task between turns waits for the task's next
execution. Cancelling such a task runs no execution, so the cancel's events
never reached the waiting subscription and its stream stayed open after the
task was canceled. CancelTask now hands the task's final snapshot to the
subscriptions still waiting, on success and when the executor's cancel
fails; a terminal snapshot ends their streams. Subscriptions register before
reading the store, so one that read the task before the cancel is waiting by
then, and one that reads it later finds it terminal.
The waiter stream drops a missing attachment with filter_map instead of an
arm no path reaches, and the tests assert whole event sequences.
Co-Authored-By: Claude Opus 5.5
Signed-off-by: gulldan <5641375+gulldan@users.noreply.github.com>
---
a2a-server/src/handler.rs | 193 +++++++++++++++++++++++++++++++-------
1 file changed, 160 insertions(+), 33 deletions(-)
diff --git a/a2a-server/src/handler.rs b/a2a-server/src/handler.rs
index 60f02874..650299a4 100644
--- a/a2a-server/src/handler.rs
+++ b/a2a-server/src/handler.rs
@@ -4,7 +4,7 @@
use a2a::*;
use async_trait::async_trait;
use futures::{
- StreamExt,
+ StreamExt, future,
stream::{self, BoxStream},
};
use std::{
@@ -103,7 +103,8 @@ struct ExecutionManager {
executions: RwLock>>,
/// Subscriptions to tasks with no registered execution, which `start`
/// attaches to the next one. Taken under `executions` by `start` and
- /// `subscribe`, alone by `Waiter::drop`, never across an await.
+ /// `subscribe`, alone by `Waiter::drop` and `release`, never across an
+ /// await.
waiting: Mutex>>>,
}
@@ -162,6 +163,17 @@ impl ExecutionManager {
}
}
+ /// Ends the subscriptions still waiting for the task's next execution
+ /// with its final snapshot: a canceled task has no execution for them to
+ /// follow, and a terminal snapshot closes their streams.
+ fn release(&self, task: &Task) {
+ let waiting = self.waiting().remove(&task.id).unwrap_or_default();
+ for waiter in waiting {
+ let (_, events) = broadcast::channel(1);
+ let _ = waiter.send((events, Some(task.clone()), 0));
+ }
+ }
+
async fn finish(&self, task_id: &str, active: &Arc) {
let mut executions = self.executions.write().await;
let should_remove = executions
@@ -191,11 +203,9 @@ impl Waiter {
/// away first.
fn into_stream(mut self) -> BoxStream<'static, Result> {
stream::once(async move { self.attached.as_mut()?.await.ok() })
- .flat_map(|attached| match attached {
- Some((receiver, snapshot_task, sequence)) => {
- subscription_stream(receiver, snapshot_task, sequence)
- }
- None => stream::empty().boxed(),
+ .filter_map(future::ready)
+ .flat_map(|(receiver, snapshot_task, sequence)| {
+ subscription_stream(receiver, snapshot_task, sequence)
})
.boxed()
}
@@ -1115,6 +1125,9 @@ impl RequestHandler for DefaultRequestHandler {
if let Some(active) = &active_execution {
active.publish(Err(&error), None).await;
}
+ if let Some(task) = ¤t_task {
+ self.execution_manager.release(task);
+ }
return Err(error);
}
}
@@ -1124,7 +1137,14 @@ impl RequestHandler for DefaultRequestHandler {
self.execution_manager.finish(&req.id, &active).await;
}
- self.load_task(&req.id).await
+ // A subscription to a task between turns has no execution to follow
+ // into the cancel; the final snapshot ends it. Subscriptions register
+ // before reading the store, so one that read the task before
+ // `begin_cancel` is waiting now, and one that reads it later finds it
+ // terminal.
+ let task = self.load_task(&req.id).await?;
+ self.execution_manager.release(&task);
+ Ok(task)
}
async fn subscribe_to_task(
@@ -1653,8 +1673,11 @@ mod tests {
}
}
- /// Asks for input on the task's first turn and completes on the next.
- struct InputRequiredExecutor;
+ /// Asks for input on the task's first turn and completes on the next;
+ /// its cancel reports the task canceled, or fails when asked to.
+ struct InputRequiredExecutor {
+ cancel_fails: bool,
+ }
impl crate::AgentExecutor for InputRequiredExecutor {
fn execute(
@@ -1680,9 +1703,23 @@ mod tests {
fn cancel(
&self,
- _ctx: ExecutorContext,
+ ctx: ExecutorContext,
) -> BoxStream<'static, Result> {
- Box::pin(stream::empty())
+ let event = if self.cancel_fails {
+ Err(A2AError::internal("cancel failed"))
+ } else {
+ Ok(StreamResponse::StatusUpdate(TaskStatusUpdateEvent {
+ task_id: ctx.task_id,
+ context_id: ctx.context_id,
+ status: TaskStatus {
+ state: TaskState::Canceled,
+ message: None,
+ timestamp: None,
+ },
+ metadata: None,
+ }))
+ };
+ Box::pin(stream::once(async move { event }))
}
}
@@ -1743,7 +1780,12 @@ mod tests {
}
fn make_input_required_handler() -> DefaultRequestHandler {
- DefaultRequestHandler::new(InputRequiredExecutor, InMemoryTaskStore::new())
+ DefaultRequestHandler::new(
+ InputRequiredExecutor {
+ cancel_fails: false,
+ },
+ InMemoryTaskStore::new(),
+ )
}
/// A task whose first turn ended asking for input: stored, but with no
@@ -1761,9 +1803,11 @@ mod tests {
)
.await
.unwrap();
- let SendMessageResponse::Task(task) = response else {
- panic!("expected a task");
- };
+ let mut task = None;
+ if let SendMessageResponse::Task(sent) = response {
+ task = Some(sent);
+ }
+ let task = task.expect("expected a task");
assert_eq!(task.status.state, TaskState::InputRequired);
assert!(handler.execution_manager.get(&task.id).await.is_none());
task
@@ -3110,6 +3154,92 @@ mod tests {
}
}
+ #[tokio::test]
+ async fn test_cancel_ends_a_subscription_to_a_task_awaiting_input() {
+ let handler = make_input_required_handler();
+ let params = ServiceParams::new();
+ let task = task_awaiting_input(&handler).await;
+ let subscription = handler
+ .subscribe_to_task(
+ ¶ms,
+ SubscribeToTaskRequest {
+ id: task.id.clone(),
+ tenant: None,
+ },
+ )
+ .await
+ .unwrap();
+
+ let canceled = handler
+ .cancel_task(
+ ¶ms,
+ CancelTaskRequest {
+ id: task.id.clone(),
+ metadata: None,
+ tenant: None,
+ },
+ )
+ .await
+ .unwrap();
+ assert_eq!(canceled.status.state, TaskState::Canceled);
+
+ // The stored task, then the canceled one, and the stream ends.
+ let events: Vec<_> = timeout(Duration::from_secs(5), subscription.collect())
+ .await
+ .expect("the subscription outlived the canceled task");
+ assert!(matches!(
+ events.as_slice(),
+ [Ok(StreamResponse::Task(stored)), Ok(StreamResponse::Task(last))]
+ if stored.status.state == TaskState::InputRequired
+ && last.status.state == TaskState::Canceled
+ ));
+ assert!(handler.execution_manager.waiting().is_empty());
+ }
+
+ #[tokio::test]
+ async fn test_cancel_failing_in_the_executor_still_ends_a_waiting_subscription() {
+ let handler = DefaultRequestHandler::new(
+ InputRequiredExecutor { cancel_fails: true },
+ InMemoryTaskStore::new(),
+ );
+ let params = ServiceParams::new();
+ let task = task_awaiting_input(&handler).await;
+ let subscription = handler
+ .subscribe_to_task(
+ ¶ms,
+ SubscribeToTaskRequest {
+ id: task.id.clone(),
+ tenant: None,
+ },
+ )
+ .await
+ .unwrap();
+
+ let error = handler
+ .cancel_task(
+ ¶ms,
+ CancelTaskRequest {
+ id: task.id.clone(),
+ metadata: None,
+ tenant: None,
+ },
+ )
+ .await
+ .unwrap_err();
+ assert_eq!(error.message, "cancel failed");
+
+ // The store holds the task canceled before the executor ran.
+ let events: Vec<_> = timeout(Duration::from_secs(5), subscription.collect())
+ .await
+ .expect("the subscription outlived the canceled task");
+ assert!(matches!(
+ events.as_slice(),
+ [Ok(StreamResponse::Task(stored)), Ok(StreamResponse::Task(last))]
+ if stored.status.state == TaskState::InputRequired
+ && last.status.state == TaskState::Canceled
+ ));
+ }
+
#[tokio::test]
async fn test_subscriptions_to_a_task_awaiting_input_follow_its_next_turn() {
let handler = make_input_required_handler();
@@ -3149,24 +3279,21 @@ mod tests {
SendMessageResponse::Task(task) if task.status.state == TaskState::Completed
));
- let states = |events: Vec>| {
- events
- .into_iter()
- .map(|event| match event.unwrap() {
- StreamResponse::Task(task) => task.status.state,
- StreamResponse::StatusUpdate(update) => update.status.state,
- other => panic!("unexpected event {other:?}"),
- })
- .collect::>()
- };
// The stored task, the task as the turn found it, then the turn.
- let expected = [
- TaskState::InputRequired,
- TaskState::InputRequired,
- TaskState::Completed,
- ];
- assert_eq!(states(first.collect().await), expected);
- assert_eq!(states(second.collect().await), expected);
+ let follows_the_turn = |events: Vec>| {
+ matches!(
+ events.as_slice(),
+ [
+ Ok(StreamResponse::Task(stored)),
+ Ok(StreamResponse::Task(found)),
+ Ok(StreamResponse::StatusUpdate(turn)),
+ ] if stored.status.state == TaskState::InputRequired
+ && found.status.state == TaskState::InputRequired
+ && turn.status.state == TaskState::Completed
+ )
+ };
+ assert!(follows_the_turn(first.collect().await));
+ assert!(follows_the_turn(second.collect().await));
// Over: a new subscription is refused as for any finished task.
let result = handler.subscribe_to_task(¶ms, subscribe()).await;
From 34940922e8766b2d08058896598926a9536825c8 Mon Sep 17 00:00:00 2001
From: gulldan <5641375+gulldan@users.noreply.github.com>
Date: Sun, 1 Nov 2026 14:10:19 +0300
Subject: [PATCH 08/14] fix(server): include tasks stamped at the
statusTimestampAfter bound
The proto defines statusTimestampAfter as "greater than or equal to", but
InMemoryTaskStore dropped a task whose status timestamp equalled the bound.
A caller that polls with the timestamp of the last task it saw never gets
that task back. The filter now keeps the bound itself.
Signed-off-by: gulldan <5641375+gulldan@users.noreply.github.com>
---
a2a-server/src/task_store/inmemory.rs | 17 ++++++++++++-----
1 file changed, 12 insertions(+), 5 deletions(-)
diff --git a/a2a-server/src/task_store/inmemory.rs b/a2a-server/src/task_store/inmemory.rs
index e8b7e270..89502625 100644
--- a/a2a-server/src/task_store/inmemory.rs
+++ b/a2a-server/src/task_store/inmemory.rs
@@ -160,14 +160,16 @@ impl TaskStore for InMemoryTaskStore {
}
}
// A task without a status timestamp cannot satisfy an
- // "after" filter. Keep this predicate in the store so the
- // result count and pagination are based on the filtered set.
+ // "after" filter, and one stamped at the bound does (the
+ // proto: "greater than or equal"). Keep this predicate in the
+ // store so the result count and pagination are based on the
+ // filtered set.
if let Some(after) = req.status_timestamp_after {
if entry
.task
.status
.timestamp
- .is_none_or(|timestamp| timestamp <= after)
+ .is_none_or(|timestamp| timestamp < after)
{
return false;
}
@@ -497,6 +499,11 @@ mod tests {
recent.status.timestamp = Some(cutoff + chrono::Duration::seconds(1));
store.create(recent).await.unwrap();
+ // The bound itself is included: "greater than or equal".
+ let mut at_cutoff = make_task("at-cutoff", "c1", TaskState::Completed);
+ at_cutoff.status.timestamp = Some(cutoff);
+ store.create(at_cutoff).await.unwrap();
+
// Missing timestamps do not satisfy an "after" filter.
store
.create(make_task("missing", "c1", TaskState::Completed))
@@ -517,13 +524,13 @@ mod tests {
.await
.unwrap();
- assert_eq!(resp.total_size, 1);
+ assert_eq!(resp.total_size, 2);
assert_eq!(
resp.tasks
.iter()
.map(|task| task.id.as_str())
.collect::>(),
- ["recent"]
+ ["at-cutoff", "recent"]
);
}
From 0c8856f6a7f10183bada3e4bc80d44ef71287ee7 Mon Sep 17 00:00:00 2001
From: gulldan <5641375+gulldan@users.noreply.github.com>
Date: Sun, 1 Nov 2026 14:10:19 +0300
Subject: [PATCH 09/14] fix(a2a-pb): keep the REQUIRED fields of
ListTasksResponse and AgentCard
proto3-JSON leaves out fields at their default, so an empty ListTasks page
came out as {"nextPageToken":"","pageSize":50} and an extended card without
skills or modes lost skills, defaultInputModes and defaultOutputModes.
Section 5.7 says REQUIRED fields MUST be present. The ListTasksResponse
normalisation that already restores nextPageToken now restores tasks,
pageSize and totalSize too, and AgentCard gets the same for its REQUIRED
top-level fields.
Signed-off-by: gulldan <5641375+gulldan@users.noreply.github.com>
---
a2a-pb/src/protojson_conv.rs | 102 ++++++++++++++++++++++++++++++-----
1 file changed, 90 insertions(+), 12 deletions(-)
diff --git a/a2a-pb/src/protojson_conv.rs b/a2a-pb/src/protojson_conv.rs
index fb8c609c..cce8c002 100644
--- a/a2a-pb/src/protojson_conv.rs
+++ b/a2a-pb/src/protojson_conv.rs
@@ -92,6 +92,16 @@ fn normalize_timestamp_strings(value: &mut Value) {
}
}
+/// Spec §5.7: a REQUIRED field MUST be present, so the defaults proto3-JSON
+/// leaves out are written back.
+fn insert_required(value: &mut Value, defaults: Value) {
+ if let (Value::Object(map), Value::Object(defaults)) = (value, defaults) {
+ for (key, default) in defaults {
+ map.entry(key).or_insert(default);
+ }
+ }
+}
+
pub fn from_value(value: Value) -> Result {
let protojson: T::ProtoJson =
serde_json::from_value(value).map_err(ProtoJsonPayloadError::Json)?;
@@ -239,12 +249,13 @@ impl ProtoJsonPayload for ListTasksResponse {
/// REQ-TASK-LIST-002: `nextPageToken` must always be present, even on
/// the last page, but the generated serializer follows proto3-JSON's
- /// own convention of omitting a string left at its default ("").
+ /// own convention of omitting a string left at its default (""). The
+ /// other REQUIRED fields go the same way on an empty page.
fn normalize_json(value: &mut Value) {
- if let Value::Object(map) = value {
- map.entry("nextPageToken")
- .or_insert_with(|| Value::String(String::new()));
- }
+ insert_required(
+ value,
+ serde_json::json!({"tasks": [], "nextPageToken": "", "pageSize": 0, "totalSize": 0}),
+ );
}
}
impl_protojson_payload!(
@@ -254,13 +265,35 @@ impl_protojson_payload!(
crate::pbconv::to_proto_list_task_push_notification_configs_response,
crate::pbconv::from_proto_list_task_push_notification_configs_response
);
-impl_protojson_payload!(
- AgentCard,
- crate::proto::AgentCard,
- crate::protojson::AgentCard,
- crate::pbconv::to_proto_agent_card,
- crate::pbconv::from_proto_agent_card
-);
+impl ProtoJsonPayload for AgentCard {
+ type Proto = crate::proto::AgentCard;
+ type ProtoJson = crate::protojson::AgentCard;
+
+ fn to_proto(value: &Self) -> Self::Proto {
+ crate::pbconv::to_proto_agent_card(value)
+ }
+
+ fn try_from_proto(value: &Self::Proto) -> Result {
+ Ok(crate::pbconv::from_proto_agent_card(value))
+ }
+
+ /// An extended card without skills or input/output modes still carries
+ /// its REQUIRED top-level fields.
+ fn normalize_json(value: &mut Value) {
+ insert_required(
+ value,
+ serde_json::json!({
+ "name": "",
+ "description": "",
+ "supportedInterfaces": [],
+ "version": "",
+ "defaultInputModes": [],
+ "defaultOutputModes": [],
+ "skills": []
+ }),
+ );
+ }
+}
impl_protojson_payload_optional!(
SendMessageResponse,
crate::proto::SendMessageResponse,
@@ -297,6 +330,51 @@ mod tests {
);
}
+ /// §5.7: every REQUIRED field of an empty page is present.
+ #[test]
+ fn test_empty_list_tasks_response_keeps_every_required_field() {
+ let response = ListTasksResponse {
+ tasks: vec![],
+ next_page_token: String::new(),
+ page_size: 0,
+ total_size: 0,
+ };
+ assert_eq!(
+ to_value(&response).unwrap(),
+ serde_json::json!({"tasks": [], "nextPageToken": "", "pageSize": 0, "totalSize": 0})
+ );
+ }
+
+ /// §5.7: a card with no skills or modes keeps its REQUIRED fields.
+ #[test]
+ fn test_agent_card_keeps_empty_required_fields() {
+ let card: AgentCard = serde_json::from_value(serde_json::json!({
+ "name": "agent",
+ "description": "",
+ "supportedInterfaces": [],
+ "version": "1.0.0",
+ "capabilities": {},
+ "defaultInputModes": [],
+ "defaultOutputModes": [],
+ "skills": []
+ }))
+ .unwrap();
+ let json = to_value(&card).unwrap();
+ for key in [
+ "name",
+ "description",
+ "supportedInterfaces",
+ "version",
+ "defaultInputModes",
+ "defaultOutputModes",
+ "skills",
+ ] {
+ assert!(json.get(key).is_some(), "{key} missing from {json}");
+ }
+ let decoded: AgentCard = from_value(json).unwrap();
+ assert_eq!(decoded, card);
+ }
+
#[test]
fn test_list_tasks_response_keeps_a_non_empty_next_page_token() {
let response = ListTasksResponse {
From c19c6ee5f147e62cf1d83e01b78aab9f0c7f74c3 Mon Sep 17 00:00:00 2001
From: gulldan <5641375+gulldan@users.noreply.github.com>
Date: Sun, 1 Nov 2026 14:10:19 +0300
Subject: [PATCH 10/14] fix(server): omit task artifacts from ListTasks unless
asked
ListTasks returned every stored artifact whatever includeArtifacts said.
Section 3.1.4 of the spec makes the default false and says the artifacts
field MUST be omitted entirely then. DefaultRequestHandler::list_tasks now
drops them unless the request sets includeArtifacts to true, next to the
historyLength trim, so any TaskStore gets the same behaviour.
Signed-off-by: gulldan <5641375+gulldan@users.noreply.github.com>
---
a2a-server/src/handler.rs | 59 +++++++++++++++++++++++++++++++++++++++
1 file changed, 59 insertions(+)
diff --git a/a2a-server/src/handler.rs b/a2a-server/src/handler.rs
index 650299a4..66c18cb5 100644
--- a/a2a-server/src/handler.rs
+++ b/a2a-server/src/handler.rs
@@ -1040,6 +1040,10 @@ impl RequestHandler for DefaultRequestHandler {
response.tasks.truncate(page_size);
for task in &mut response.tasks {
apply_history_length(task, req.history_length);
+ // §3.1.4: artifacts are omitted unless the caller asks for them.
+ if req.include_artifacts != Some(true) {
+ task.artifacts = None;
+ }
}
Ok(response)
}
@@ -2674,6 +2678,61 @@ mod tests {
assert!(resp.tasks.is_empty());
}
+ /// ListTasks omits artifacts unless `includeArtifacts` is true (§3.1.4).
+ #[tokio::test]
+ async fn test_list_tasks_includes_artifacts_only_on_request() {
+ let store = InMemoryTaskStore::new();
+ store
+ .create(Task {
+ id: "t-artifact".into(),
+ context_id: "ctx".into(),
+ status: TaskStatus {
+ state: TaskState::Completed,
+ message: None,
+ timestamp: Some(chrono::Utc::now()),
+ },
+ artifacts: Some(vec![Artifact {
+ artifact_id: "a1".into(),
+ name: None,
+ description: None,
+ parts: vec![Part::text("result")],
+ metadata: None,
+ extensions: None,
+ }]),
+ history: None,
+ metadata: None,
+ })
+ .await
+ .unwrap();
+ let handler = DefaultRequestHandler::new(EchoExecutor, store);
+ let params = ServiceParams::new();
+ for (include_artifacts, expected) in
+ [(None, false), (Some(false), false), (Some(true), true)]
+ {
+ let resp = handler
+ .list_tasks(
+ ¶ms,
+ ListTasksRequest {
+ context_id: None,
+ status: None,
+ page_size: None,
+ page_token: None,
+ history_length: None,
+ status_timestamp_after: None,
+ include_artifacts,
+ tenant: None,
+ },
+ )
+ .await
+ .unwrap();
+ assert_eq!(
+ resp.tasks[0].artifacts.is_some(),
+ expected,
+ "include_artifacts={include_artifacts:?}"
+ );
+ }
+ }
+
#[tokio::test]
async fn test_cancel_task_not_found() {
let handler = make_handler();
From 6880e73a4dcc01f83e0e8c473346658690d1e025 Mon Sep 17 00:00:00 2001
From: gulldan <5641375+gulldan@users.noreply.github.com>
Date: Sun, 1 Nov 2026 14:10:19 +0300
Subject: [PATCH 11/14] fix(server): send push credentials of any
authentication scheme
HttpPushSender sent an Authorization header only for Bearer and Basic and
silently dropped every other scheme, so a webhook expecting e.g. DPoP got
an unauthenticated request. Section 4.3.3 says the agent MUST include the
credentials of TaskPushNotificationConfig.authentication. Any scheme is now
sent as " "; Bearer and Basic keep their canonical
spelling, and a scheme that is not a single token is rejected like CR/LF in
the credentials.
Signed-off-by: gulldan <5641375+gulldan@users.noreply.github.com>
---
a2a-server/src/push/sender.rs | 110 +++++++++++++++++++++++++++-------
1 file changed, 87 insertions(+), 23 deletions(-)
diff --git a/a2a-server/src/push/sender.rs b/a2a-server/src/push/sender.rs
index 8d7bddc1..f6a9c3da 100644
--- a/a2a-server/src/push/sender.rs
+++ b/a2a-server/src/push/sender.rs
@@ -104,6 +104,17 @@ impl HttpPushSender {
"push credentials must not contain CR/LF",
));
}
+ // The scheme opens the Authorization header, so it must be a
+ // single HTTP auth-scheme token (RFC 9110 §11.1).
+ if auth.scheme.is_empty()
+ || auth
+ .scheme
+ .contains(|c: char| c.is_whitespace() || c.is_control())
+ {
+ return Err(A2AError::invalid_params(
+ "push authentication scheme must be a single token",
+ ));
+ }
}
}
@@ -124,15 +135,14 @@ impl HttpPushSender {
if let Some(ref auth) = config.authentication {
if let Some(ref creds) = auth.credentials {
- match auth.scheme.to_lowercase().as_str() {
- "bearer" => {
- request = request.header("Authorization", format!("Bearer {creds}"));
- }
- "basic" => {
- request = request.header("Authorization", format!("Basic {creds}"));
- }
- _ => {}
- }
+ // Any IANA scheme is sent as configured (§4.3.3); the two
+ // common ones keep their canonical spelling.
+ let scheme = match auth.scheme.to_lowercase().as_str() {
+ "bearer" => "Bearer",
+ "basic" => "Basic",
+ _ => auth.scheme.as_str(),
+ };
+ request = request.header("Authorization", format!("{scheme} {creds}"));
}
}
@@ -463,26 +473,80 @@ mod tests {
assert!(result.is_ok()); // fail_on_error=false
}
+ /// Runs a webhook that records the Authorization header of each request.
+ async fn spawn_auth_recorder() -> (String, Arc>>>) {
+ let seen = Arc::new(std::sync::Mutex::new(Vec::new()));
+ let log = Arc::clone(&seen);
+ let app = axum::Router::new().route(
+ "/callback",
+ axum::routing::post(move |headers: axum::http::HeaderMap| {
+ let log = Arc::clone(&log);
+ async move {
+ log.lock().unwrap().push(
+ headers
+ .get("authorization")
+ .map(|value| value.to_str().unwrap().to_owned()),
+ );
+ }
+ }),
+ );
+ let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
+ let addr = listener.local_addr().unwrap();
+ tokio::spawn(async move { axum::serve(listener, app).await });
+ (format!("http://{addr}/callback"), seen)
+ }
+
#[tokio::test]
- async fn test_send_push_with_unknown_auth_scheme() {
+ async fn test_send_push_sends_credentials_of_any_scheme() {
install_crypto_provider();
let sender = HttpPushSender::new(Some(HttpPushSenderConfig {
+ fail_on_error: true,
validate_urls: false,
..Default::default()
}));
- let config = TaskPushNotificationConfig {
- task_id: String::new(),
- url: "http://127.0.0.1:1/callback".to_string(),
- id: None,
- token: None,
- authentication: Some(AuthenticationInfo {
- scheme: "custom".to_string(),
- credentials: Some("cred".to_string()),
- }),
- tenant: None,
- };
- let result = sender.send_push(&config, sample_status_update()).await;
- assert!(result.is_ok());
+ let (url, seen) = spawn_auth_recorder().await;
+ for (scheme, expected) in [
+ ("bearer", "Bearer tok"),
+ ("Basic", "Basic tok"),
+ ("DPoP", "DPoP tok"),
+ ] {
+ let config = TaskPushNotificationConfig {
+ authentication: Some(AuthenticationInfo {
+ scheme: scheme.to_string(),
+ credentials: Some("tok".to_string()),
+ }),
+ ..sample_config(&url)
+ };
+ sender
+ .send_push(&config, sample_status_update())
+ .await
+ .unwrap();
+ assert_eq!(
+ seen.lock().unwrap().last().unwrap().as_deref(),
+ Some(expected),
+ "scheme {scheme}"
+ );
+ }
+ }
+
+ #[tokio::test]
+ async fn test_send_push_rejects_a_scheme_that_is_not_one_token() {
+ install_crypto_provider();
+ let sender = HttpPushSender::new(None);
+ for scheme in ["", "Bearer x", "Bearer\r\nX-Injected: 1"] {
+ let config = TaskPushNotificationConfig {
+ authentication: Some(AuthenticationInfo {
+ scheme: scheme.to_string(),
+ credentials: Some("tok".to_string()),
+ }),
+ ..sample_config("https://example.com/callback")
+ };
+ let error = sender
+ .send_push(&config, sample_status_update())
+ .await
+ .unwrap_err();
+ assert_eq!(error.code, error_code::INVALID_PARAMS, "scheme {scheme:?}");
+ }
}
#[test]
From d610495a9a99c6e847e0335636afcc8cc60374f6 Mon Sep 17 00:00:00 2001
From: gulldan <5641375+gulldan@users.noreply.github.com>
Date: Sun, 1 Nov 2026 14:10:19 +0300
Subject: [PATCH 12/14] fix(rest): send stream errors as google.rpc.Status
An error inside an HTTP+JSON stream went out as a bare JSON-RPC error
object, and the REST client failed to parse it, so the caller saw
"SSE parse error" (-32603) instead of the typed error. Section 11.6 says
HTTP+JSON errors use the {"error": google.rpc.Status} body. The REST
binding now sends that body as the stream event, built by the same code as
a non-streaming error response, and the REST client reads it back into the
typed A2AError, through the same parser it uses for error responses.
Signed-off-by: gulldan <5641375+gulldan@users.noreply.github.com>
---
a2a-client/src/jsonrpc.rs | 22 ++++++++++++++++
a2a-client/src/rest.rs | 13 +++++----
a2a-server/src/rest.rs | 55 ++++++++++++++++++++++++++++++++++-----
3 files changed, 78 insertions(+), 12 deletions(-)
diff --git a/a2a-client/src/jsonrpc.rs b/a2a-client/src/jsonrpc.rs
index 87ea8b0c..f69f2338 100644
--- a/a2a-client/src/jsonrpc.rs
+++ b/a2a-client/src/jsonrpc.rs
@@ -427,6 +427,9 @@ pub(crate) fn parse_sse_stream_rest(
if data.is_empty() {
return None;
}
+ if let Some(error) = crate::rest::rest_error(&data) {
+ return Some(Err(error));
+ }
match protojson_conv::from_str::(&data) {
Ok(sr) => Some(Ok(sr)),
@@ -844,6 +847,25 @@ mod tests {
assert!(matches!(item, StreamResponse::StatusUpdate(_)));
}
+ #[tokio::test]
+ async fn test_parse_sse_stream_rest_error_event_keeps_its_code() {
+ let error = serde_json::json!({"error": {
+ "code": 404,
+ "status": "NOT_FOUND",
+ "message": "task not found: t1",
+ "details": [{
+ "@type": "type.googleapis.com/google.rpc.ErrorInfo",
+ "reason": "TASK_NOT_FOUND",
+ "domain": "a2a-protocol.org"
+ }]
+ }});
+ let stream = byte_stream(vec![format!("data: {error}\n\n")]);
+ let mut parsed = parse_sse_stream_rest(stream);
+ let err = parsed.next().await.unwrap().unwrap_err();
+ assert_eq!(err.code, error_code::TASK_NOT_FOUND);
+ assert_eq!(err.message, "task not found: t1");
+ }
+
#[tokio::test]
async fn test_parse_sse_stream_rest_parse_error() {
let sse_text = "data: not-valid-json\n\n".to_string();
diff --git a/a2a-client/src/rest.rs b/a2a-client/src/rest.rs
index b0d757b4..36fc0bd6 100644
--- a/a2a-client/src/rest.rs
+++ b/a2a-client/src/rest.rs
@@ -241,15 +241,18 @@ impl RestTransport {
}
fn parse_rest_error(status: reqwest::StatusCode, body: &str) -> A2AError {
- let Ok(envelope) = serde_json::from_str::(body) else {
- return A2AError::internal(format!("HTTP {status}: {body}"));
- };
+ rest_error(body).unwrap_or_else(|| A2AError::internal(format!("HTTP {status}: {body}")))
+}
- crate::a2a_error_from_details(
+/// The `{"error": google.rpc.Status}` body of an HTTP+JSON error, which a
+/// stream also sends in-band as an event (§11.6).
+pub(crate) fn rest_error(body: &str) -> Option {
+ let envelope = serde_json::from_str::(body).ok()?;
+ Some(crate::a2a_error_from_details(
error_code::INTERNAL_ERROR,
envelope.error.message,
envelope.error.details,
- )
+ ))
}
fn should_retry_subscribe_with_legacy_path(err: &A2AError) -> bool {
diff --git a/a2a-server/src/rest.rs b/a2a-server/src/rest.rs
index 7363a948..a8d58324 100644
--- a/a2a-server/src/rest.rs
+++ b/a2a-server/src/rest.rs
@@ -174,7 +174,7 @@ async fn handle_stream_message(
};
let params = extract_service_params(&headers);
match state.handler.send_streaming_message(¶ms, req).await {
- Ok(stream) => sse::sse_from_stream(protojson_stream(stream)).into_response(),
+ Ok(stream) => rest_sse(protojson_stream(stream)),
Err(e) => rest_error_response(e),
}
}
@@ -315,7 +315,7 @@ async fn handle_subscribe_to_task_inner(
) -> axum::response::Response {
let req = SubscribeToTaskRequest { id, tenant: None };
match state.handler.subscribe_to_task(¶ms, req).await {
- Ok(stream) => sse::sse_from_stream(protojson_stream(stream)).into_response(),
+ Ok(stream) => rest_sse(protojson_stream(stream)),
Err(e) => rest_error_response(e),
}
}
@@ -457,6 +457,17 @@ fn protojson_stream(
}))
}
+/// Spec §11.6: an error inside an HTTP+JSON stream is an event carrying the
+/// same `{"error": google.rpc.Status}` body a non-streaming error has.
+fn rest_sse(stream: BoxStream<'static, Result>) -> axum::response::Response {
+ let events = stream.map(|item| {
+ Ok(item.unwrap_or_else(|err| {
+ serde_json::to_value(rest_error_envelope(err).1).unwrap_or_default()
+ }))
+ });
+ sse::sse_from_stream(Box::pin(events)).into_response()
+}
+
fn parse_create_push_config_request(
task_id: String,
raw_config: Value,
@@ -488,6 +499,14 @@ fn rest_payload_error_response(error: impl std::fmt::Display) -> axum::response:
}
fn rest_error_response(err: A2AError) -> axum::response::Response {
+ let (status, body) = rest_error_envelope(err);
+ with_content_type(
+ (status, Json(body)).into_response(),
+ "application/problem+json",
+ )
+}
+
+fn rest_error_envelope(err: A2AError) -> (StatusCode, RestErrorEnvelope) {
let status =
StatusCode::from_u16(err.http_status_code()).unwrap_or(StatusCode::INTERNAL_SERVER_ERROR);
let reason = error_reason(err.code);
@@ -526,11 +545,7 @@ fn rest_error_response(err: A2AError) -> axum::response::Response {
details,
},
};
-
- with_content_type(
- (status, Json(body)).into_response(),
- "application/problem+json",
- )
+ (status, body)
}
fn rest_grpc_status(code: i32) -> &'static str {
@@ -968,6 +983,32 @@ mod tests {
assert_eq!(err.message, "Internal error");
}
+ #[tokio::test]
+ async fn test_stream_error_event_is_a_google_rpc_status() {
+ let stream: BoxStream<'static, Result> =
+ Box::pin(futures::stream::iter(vec![
+ Ok(serde_json::json!({"statusUpdate": {}})),
+ Err(A2AError::task_not_found("t1")),
+ ]));
+ let body = rest_sse(stream)
+ .into_body()
+ .collect()
+ .await
+ .unwrap()
+ .to_bytes();
+ let frames: Vec = String::from_utf8(body.to_vec())
+ .unwrap()
+ .lines()
+ .filter_map(|line| line.strip_prefix("data: "))
+ .map(|data| serde_json::from_str(data).unwrap())
+ .collect();
+ assert_eq!(frames.len(), 2);
+ let error = &frames[1]["error"];
+ assert_eq!(error["code"], 404);
+ assert_eq!(error["status"], "NOT_FOUND");
+ assert_eq!(error["details"][0]["reason"], "TASK_NOT_FOUND");
+ }
+
#[tokio::test]
async fn test_rest_error_response_merges_error_info_metadata() {
let existing_info = TypedDetail::error_info(
From 62491099e7bdff5e8f7f17339308fe468f967b7f Mon Sep 17 00:00:00 2001
From: gulldan <5641375+gulldan@users.noreply.github.com>
Date: Sun, 1 Nov 2026 16:23:37 +0300
Subject: [PATCH 13/14] fix(client): percent-encode task and config ids in REST
paths
The REST transport put `req.id` and `req.task_id` into the URL path as they
were, so `/`, `?`, `#` and `%` in an id changed the request: the id
`../admin?x=1` requested `/a2a/admin?x=1`, and `#` cut `:cancel` off into
the fragment. Every id is now one path segment with everything but the
RFC 3986 unreserved characters percent-encoded.
Signed-off-by: gulldan <5641375+gulldan@users.noreply.github.com>
---
Cargo.lock | 1 +
a2a-client/Cargo.toml | 1 +
a2a-client/src/rest.rs | 98 ++++++++++++++++++++++++++++++++++++++----
3 files changed, 92 insertions(+), 8 deletions(-)
diff --git a/Cargo.lock b/Cargo.lock
index d4f41e54..8125b2dd 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -36,6 +36,7 @@ dependencies = [
"auto_impl",
"bytes",
"futures",
+ "percent-encoding",
"pin-project-lite",
"rcgen",
"reqwest",
diff --git a/a2a-client/Cargo.toml b/a2a-client/Cargo.toml
index 39e7b16e..b0810c70 100644
--- a/a2a-client/Cargo.toml
+++ b/a2a-client/Cargo.toml
@@ -27,6 +27,7 @@ async-trait = { workspace = true }
auto_impl = { workspace = true }
reqwest = { workspace = true }
bytes = "1"
+percent-encoding = "2"
tracing = { workspace = true }
uuid = { workspace = true }
semver = { workspace = true }
diff --git a/a2a-client/src/rest.rs b/a2a-client/src/rest.rs
index 36fc0bd6..d99770c0 100644
--- a/a2a-client/src/rest.rs
+++ b/a2a-client/src/rest.rs
@@ -5,6 +5,7 @@ use a2a::*;
use a2a_pb::protojson_conv::{self, ProtoJsonPayload};
use async_trait::async_trait;
use futures::stream::BoxStream;
+use percent_encoding::{AsciiSet, NON_ALPHANUMERIC, PercentEncode, utf8_percent_encode};
use reqwest::Client;
use serde::Deserialize;
use serde_json::Value;
@@ -20,6 +21,18 @@ const REST_SEND_MESSAGE_PATH: &str = "/message:send";
const REST_STREAM_MESSAGE_PATH: &str = "/message:stream";
const REST_EXTENDED_AGENT_CARD_PATH: &str = "/extendedAgentCard";
+/// Everything but the RFC 3986 unreserved characters is percent-encoded, so an
+/// id always stays one path segment (`/`, `?`, `#` and `%` in it change nothing).
+const PATH_SEGMENT: &AsciiSet = &NON_ALPHANUMERIC
+ .remove(b'-')
+ .remove(b'.')
+ .remove(b'_')
+ .remove(b'~');
+
+fn segment(id: &str) -> PercentEncode<'_> {
+ utf8_percent_encode(id, PATH_SEGMENT)
+}
+
#[derive(Debug, Deserialize)]
struct RestErrorEnvelope {
error: RestErrorStatus,
@@ -295,7 +308,7 @@ impl Transport for RestTransport {
params: &ServiceParams,
req: &GetTaskRequest,
) -> Result {
- let path = format!("/tasks/{}", req.id);
+ let path = format!("/tasks/{}", segment(&req.id));
let mut query_parts = Vec::new();
if let Some(hl) = req.history_length {
query_parts.push(("historyLength".to_string(), hl.to_string()));
@@ -342,7 +355,7 @@ impl Transport for RestTransport {
params: &ServiceParams,
req: &CancelTaskRequest,
) -> Result {
- self.post_json(&format!("/tasks/{}:cancel", req.id), params, req)
+ self.post_json(&format!("/tasks/{}:cancel", segment(&req.id)), params, req)
.await
}
@@ -351,11 +364,11 @@ impl Transport for RestTransport {
params: &ServiceParams,
req: &SubscribeToTaskRequest,
) -> Result>, A2AError> {
- let canonical_path = format!("/tasks/{}:subscribe", req.id);
+ let canonical_path = format!("/tasks/{}:subscribe", segment(&req.id));
match self.get_streaming(&canonical_path, params).await {
Ok(stream) => Ok(stream),
Err(err) if should_retry_subscribe_with_legacy_path(&err) => {
- self.get_streaming(&format!("/tasks/{}/subscribe", req.id), params)
+ self.get_streaming(&format!("/tasks/{}/subscribe", segment(&req.id)), params)
.await
}
Err(err) => Err(err),
@@ -369,7 +382,7 @@ impl Transport for RestTransport {
) -> Result {
let payload = self
.post_value(
- &format!("/tasks/{}/pushNotificationConfigs", req.task_id),
+ &format!("/tasks/{}/pushNotificationConfigs", segment(&req.task_id)),
params,
req,
)
@@ -384,7 +397,11 @@ impl Transport for RestTransport {
) -> Result {
let payload = self
.get_value(
- &format!("/tasks/{}/pushNotificationConfigs/{}", req.task_id, req.id),
+ &format!(
+ "/tasks/{}/pushNotificationConfigs/{}",
+ segment(&req.task_id),
+ segment(&req.id)
+ ),
params,
&[],
)
@@ -407,7 +424,7 @@ impl Transport for RestTransport {
let payload = self
.get_value(
- &format!("/tasks/{}/pushNotificationConfigs", req.task_id),
+ &format!("/tasks/{}/pushNotificationConfigs", segment(&req.task_id)),
params,
&query_parts,
)
@@ -421,7 +438,11 @@ impl Transport for RestTransport {
req: &DeleteTaskPushNotificationConfigRequest,
) -> Result<(), A2AError> {
self.delete(
- &format!("/tasks/{}/pushNotificationConfigs/{}", req.task_id, req.id),
+ &format!(
+ "/tasks/{}/pushNotificationConfigs/{}",
+ segment(&req.task_id),
+ segment(&req.id)
+ ),
params,
)
.await
@@ -575,6 +596,67 @@ mod tests {
format!("http://{addr}")
}
+ /// Answers one request with a task and hands back its request line.
+ async fn spawn_request_line_server() -> (String, tokio::sync::oneshot::Receiver) {
+ let listener = TcpListener::bind("127.0.0.1:0").await.unwrap();
+ let addr = listener.local_addr().unwrap();
+ let (tx, rx) = tokio::sync::oneshot::channel();
+
+ tokio::spawn(async move {
+ let (mut socket, _) = listener.accept().await.unwrap();
+ let request = read_http_request(&mut socket).await;
+ let _ = tx.send(request.lines().next().unwrap_or_default().to_owned());
+ let body =
+ json!({"id": "t", "contextId": "c", "status": {"state": "TASK_STATE_WORKING"}})
+ .to_string();
+ let response = format!(
+ "HTTP/1.1 200 OK\r\ncontent-type: application/json\r\ncontent-length: {}\r\nconnection: close\r\n\r\n{}",
+ body.len(),
+ body,
+ );
+ socket.write_all(response.as_bytes()).await.unwrap();
+ });
+
+ (format!("http://{addr}/a2a"), rx)
+ }
+
+ #[tokio::test]
+ async fn test_task_ids_are_percent_encoded_into_one_path_segment() {
+ let (url, line) = spawn_request_line_server().await;
+ let transport = RestTransport::new(crate::default_reqwest_client(None).unwrap(), url);
+ let _ = transport
+ .get_task(
+ &ServiceParams::new(),
+ &GetTaskRequest {
+ id: "../admin?x=1".into(),
+ history_length: None,
+ tenant: None,
+ },
+ )
+ .await;
+ assert_eq!(
+ line.await.unwrap(),
+ "GET /a2a/tasks/..%2Fadmin%3Fx%3D1 HTTP/1.1"
+ );
+
+ let (url, line) = spawn_request_line_server().await;
+ let transport = RestTransport::new(crate::default_reqwest_client(None).unwrap(), url);
+ let _ = transport
+ .cancel_task(
+ &ServiceParams::new(),
+ &CancelTaskRequest {
+ id: "t#1 %".into(),
+ metadata: None,
+ tenant: None,
+ },
+ )
+ .await;
+ assert_eq!(
+ line.await.unwrap(),
+ "POST /a2a/tasks/t%231%20%25:cancel HTTP/1.1"
+ );
+ }
+
#[test]
fn test_rest_transport_new_strips_trailing_slash() {
let t = RestTransport::new(
From 79073061eddca9ca6289187b500e76ded96a0301 Mon Sep 17 00:00:00 2001
From: gulldan <5641375+gulldan@users.noreply.github.com>
Date: Sun, 1 Nov 2026 16:26:26 +0300
Subject: [PATCH 14/14] fix(rest): answer extractor rejections with
google.rpc.Status
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
The HTTP+JSON handlers took their input through axum's Json and Query
extractors, so a malformed query, an undecodable body or a missing
Content-Type was answered by axum before the handler, as a plain-text
400/415/422. HTTP+JSON errors use the google.rpc.Status body (§11.6),
as #272 made the JSON-RPC router do. The rejections now go through the
invalid-request-body response the handlers already return; a body over
the size limit keeps its 413.
Signed-off-by: gulldan <5641375+gulldan@users.noreply.github.com>
---
a2a-server/src/rest.rs | 117 ++++++++++++++++++++++++++++++++++++++---
1 file changed, 110 insertions(+), 7 deletions(-)
diff --git a/a2a-server/src/rest.rs b/a2a-server/src/rest.rs
index a8d58324..a221bf33 100644
--- a/a2a-server/src/rest.rs
+++ b/a2a-server/src/rest.rs
@@ -7,7 +7,10 @@ use a2a::*;
use a2a_pb::protojson_conv::{self, ProtoJsonPayload};
use axum::{
Json,
- extract::{Path, Query, Request, State},
+ extract::{
+ Path, Query, Request, State,
+ rejection::{JsonRejection, QueryRejection},
+ },
http::{HeaderMap, HeaderValue, StatusCode, header},
middleware::Next,
response::{IntoResponse, Response},
@@ -150,8 +153,12 @@ async fn validate_protocol_version(request: Request, next: Next) -> Response {
async fn handle_send_message(
State(state): State>,
headers: HeaderMap,
- Json(raw_req): Json,
+ body: Result, JsonRejection>,
) -> impl IntoResponse {
+ let Json(raw_req) = match body {
+ Ok(body) => body,
+ Err(rejection) => return json_rejection_response(rejection),
+ };
let req = match protojson_conv::from_value::(raw_req) {
Ok(req) => req,
Err(e) => return rest_payload_error_response(e),
@@ -166,8 +173,12 @@ async fn handle_send_message(
async fn handle_stream_message(
State(state): State>,
headers: HeaderMap,
- Json(raw_req): Json,
+ body: Result, JsonRejection>,
) -> impl IntoResponse {
+ let Json(raw_req) = match body {
+ Ok(body) => body,
+ Err(rejection) => return json_rejection_response(rejection),
+ };
let req = match protojson_conv::from_value::(raw_req) {
Ok(req) => req,
Err(e) => return rest_payload_error_response(e),
@@ -205,9 +216,13 @@ async fn handle_get_task_inner(
async fn handle_get_task_or_subscribe(
State(state): State>,
Path(id): Path,
- Query(query): Query,
+ query: Result, QueryRejection>,
headers: HeaderMap,
) -> impl IntoResponse {
+ let Query(query) = match query {
+ Ok(query) => query,
+ Err(rejection) => return rest_payload_error_response(rejection.body_text()),
+ };
let params = extract_service_params(&headers);
if let Some(task_id) = id.strip_suffix(":subscribe") {
return handle_subscribe_to_task_inner(state, params, task_id.to_string()).await;
@@ -238,9 +253,13 @@ pub struct ListTasksQuery {
async fn handle_list_tasks(
State(state): State>,
- Query(query): Query,
+ query: Result, QueryRejection>,
headers: HeaderMap,
) -> impl IntoResponse {
+ let Query(query) = match query {
+ Ok(query) => query,
+ Err(rejection) => return rest_payload_error_response(rejection.body_text()),
+ };
let params = extract_service_params(&headers);
let status = match query.status {
Some(s) => match serde_json::from_value::(serde_json::Value::String(s)) {
@@ -342,8 +361,12 @@ async fn handle_create_push_config(
State(state): State>,
Path(id): Path,
headers: HeaderMap,
- Json(raw_config): Json,
+ body: Result, JsonRejection>,
) -> impl IntoResponse {
+ let Json(raw_config) = match body {
+ Ok(body) => body,
+ Err(rejection) => return json_rejection_response(rejection),
+ };
let req = match parse_create_push_config_request(id, raw_config) {
Ok(req) => req,
Err(e) => return rest_payload_error_response(e),
@@ -375,9 +398,13 @@ async fn handle_get_push_config(
async fn handle_list_push_configs(
State(state): State>,
Path(id): Path,
- Query(query): Query,
+ query: Result, QueryRejection>,
headers: HeaderMap,
) -> impl IntoResponse {
+ let Query(query) = match query {
+ Ok(query) => query,
+ Err(rejection) => return rest_payload_error_response(rejection.body_text()),
+ };
let params = extract_service_params(&headers);
let req = ListTaskPushNotificationConfigsRequest {
task_id: id,
@@ -487,6 +514,15 @@ fn parse_create_push_config_request(
})
}
+/// A body over `DefaultBodyLimit` keeps axum's 413; any other body the `Json`
+/// extractor rejects is an invalid request body like an undecodable one.
+fn json_rejection_response(rejection: JsonRejection) -> axum::response::Response {
+ if rejection.status() == StatusCode::PAYLOAD_TOO_LARGE {
+ return rejection.into_response();
+ }
+ rest_payload_error_response(rejection.body_text())
+}
+
fn rest_payload_error_response(error: impl std::fmt::Display) -> axum::response::Response {
let violation = FieldViolation {
field: String::new(),
@@ -1636,4 +1672,71 @@ mod tests {
let uri = format!("{REST_SEND_MESSAGE_PATH}?A2A-Version=99.0");
assert_version_not_supported(send_message_with_version(&uri, None).await).await;
}
+
+ /// Input axum rejects before a handler runs gets the google.rpc.Status
+ /// body of every other REST error (§11.6), not axum's plain-text rejection.
+ #[tokio::test]
+ async fn test_extractor_rejections_answer_google_rpc_status() {
+ let requests = [
+ Request::builder()
+ .uri("/tasks/t1?historyLength=abc")
+ .method("GET")
+ .header("a2a-version", "1.0")
+ .body(Body::empty())
+ .unwrap(),
+ Request::builder()
+ .uri("/tasks?pageSize=x")
+ .method("GET")
+ .header("a2a-version", "1.0")
+ .body(Body::empty())
+ .unwrap(),
+ Request::builder()
+ .uri(REST_SEND_MESSAGE_PATH)
+ .method("POST")
+ .header("a2a-version", "1.0")
+ .header("content-type", "application/json")
+ .body(Body::from("{"))
+ .unwrap(),
+ Request::builder()
+ .uri(REST_SEND_MESSAGE_PATH)
+ .method("POST")
+ .header("a2a-version", "1.0")
+ .body(Body::from("{}"))
+ .unwrap(),
+ Request::builder()
+ .uri(REST_STREAM_MESSAGE_PATH)
+ .method("POST")
+ .header("a2a-version", "1.0")
+ .header("content-type", "application/json")
+ .body(Body::from("{"))
+ .unwrap(),
+ Request::builder()
+ .uri("/tasks/t1/pushNotificationConfigs")
+ .method("POST")
+ .header("a2a-version", "1.0")
+ .header("content-type", "application/json")
+ .body(Body::from("{"))
+ .unwrap(),
+ Request::builder()
+ .uri("/tasks/t1/pushNotificationConfigs?pageSize=x")
+ .method("GET")
+ .header("a2a-version", "1.0")
+ .body(Body::empty())
+ .unwrap(),
+ ];
+ for req in requests {
+ let target = req.uri().to_string();
+ let resp = make_app().oneshot(req).await.unwrap();
+ assert_eq!(resp.status(), StatusCode::BAD_REQUEST, "{target}");
+ assert_eq!(
+ resp.headers().get("content-type").unwrap(),
+ "application/problem+json",
+ "{target}"
+ );
+ let body = resp.into_body().collect().await.unwrap().to_bytes();
+ let body: Value = serde_json::from_slice(&body).unwrap();
+ assert_eq!(body["error"]["code"], 400, "{target}");
+ assert_eq!(body["error"]["status"], "INVALID_ARGUMENT", "{target}");
+ }
+ }
}