Repository navigation
Conversation
Codecov Report❌ Patch coverage is
📢 Thoughts on this report? Let us know! |
muscariello
left a comment
There was a problem hiding this comment.
Thanks, this is the half I left for a follow-up, and it reads well. The wire order is pinned, a status without other details is byte-identical to before, and the round-trip and e2e cases cover the client side from #508.
One thing to check before merging:
Size of the details in the status. The ErrorInfo and BadRequest that went into grpc-status-details-bin were always small. It now carries whatever an agent puts in A2AError::details, and it travels in the response headers or trailers, which HTTP/2 stacks cap (I believe hyper's default is around 16 KB, from memory, not measured). A large detail could turn a clean error into a transport failure at the client, which is worse than dropping the detail. JSON-RPC and REST have no such limit. Could you add an e2e case with a detail of about 64 KB and see what the client receives? If it breaks the stream, cap the encoded size and drop the extra Structs, with a log line.
Smaller, not blocking:
- The rustdoc of
a2a_error_to_statusshould say that other details are sent asStruct, lose their@type, and pass numbers throughf64(integers above 2^53 lose precision). Status::decode(...).unwrap_or_default()would silently drop theErrorInfoandBadRequestif decoding ever failed. It can't today, since tonic just produced the bytes, but anexpect, or building theAnys directly, would say so.
Otherwise this looks good to me.
fab0e2a to
7cc9e35
Compare
|
Thanks. Measured rather than guessed: with a stock
Mirror of |
e3287e9 to
3b43b6e
Compare
|
One more revision on the cap, because the first one was not grounded: it capped the raw
So the commit now keeps the whole error trailer block within Mirror of |
3b43b6e to
a6ecb51
Compare
|
I have converted this to a draft: re-reading the sources turned up questions I would rather put to you than decide here. The commit is updated (a6ecb51, same single commit, CI mirror 977 tests, patch coverage 189/0), so the current state is visible, but the shape of the fix depends on the answers. What I found
I opened a2aproject/A2A#2433 with the sources and the SDK table, asking the specification to say which details are always sent, that the gRPC binding may drop the rest, and how a type outside What I would like to know
The rustdoc of |
`a2a_error_to_status` encoded only `ErrorInfo` and `BadRequest`, so any other `TypedDetail` on an `A2AError` (for example `TypedDetail::from_struct`) was dropped on the way to a gRPC client, while the JSON-RPC and REST transports carry it. Append every `google.protobuf.Struct` detail to the `google.rpc.Status` after the `ErrorInfo` and `BadRequest` that `tonic_types::ErrorDetails` produces; a status with no such detail is encoded exactly as before. A detail of any other type has no protobuf encoding here and is still dropped, now with a warning, rather than sent under a type URL that is not its own: the specification (§3.3.2) requires each detail's `@type` to identify its type. The status travels base64-encoded in the `grpc-status-details-bin` trailer, and a large detail turns the error into a transport failure at the client once the header list exceeds what its HTTP/2 stack accepts (hyper: 16 KiB). Keep the error trailers within the 8 KiB that gRPC clients accept by default (grpc-java's `maxInboundMetadataSize` on Netty, C-core's soft `grpc.max_metadata_size`, the limit grpc-go is moving to), measured as HTTP/2 counts a header list: the message, `ErrorInfo` and `BadRequest` come first, and the detail that does not fit and the ones after it are dropped with a warning. Co-Authored-By: Claude Mythos 5.1 <noreply@anthropic.com> Signed-off-by: gulldan <5641375+gulldan@users.noreply.github.com>
a6ecb51 to
e998882
Compare
Closes #514. Follow-up to #508.
Problem
a2a_error_to_statusencodes thegoogle.rpc.Statusthroughtonic_types::ErrorDetails, which carries onlyErrorInfoandBadRequest. Every otherTypedDetailon anA2AError(for exampleTypedDetail::from_struct) is dropped before it reaches a gRPC client, while the JSON-RPC and REST transports carry it inerror.data. Since #508 the gRPC client decodesgoogle.protobuf.Structdetails, the shape a2a-go sends, so the Rust server was the only side not sending them.Fix
ErrorDetailshas no slot for a customAny, so the function keeps buildingErrorInfo(reason from the code, protocol domain, merged metadata) andBadRequestexactly as before and, only when the error hasgoogle.protobuf.Structdetails, decodes thegoogle.rpc.Statustonic produced, appends each of them as aStructAny(errordetails::STRUCT_TYPE, value froma2a_pb::pbconv::to_proto_struct) and re-encodes it withtonic::Status::with_details. Wire order staysErrorInfo,BadRequest, then the Struct details in the order the error lists them. A status without such details is byte-identical to today's. The public signature is unchanged.A detail of any other type (say
google.rpc.RetryInfobuilt withTypedDetail::new) has no protobuf encoding here, so it is still dropped as onmain, now with atracing::warn!naming the type URL. The earlier revision sent it as aStructthe way a2a-go does; I took that back because the specification (§3.3.2) requires each detail's@typeto identify its type, and aRetryInfoarriving as aStructdoes not. Encoding the standardgoogle.rpctypes is a separate change (ProtoJSON forerror_details.protoina2a-pb). Numbers in a Struct pass throughf64, so integers above 2^53 lose precision; the rustdoc says so.The status travels base64-encoded in the
grpc-status-details-bintrailer, so a large detail turns the error into a transport failure at the client once the header list exceeds what its HTTP/2 stack accepts: measured withGrpcTransport(hyper: 16 KiB), a Struct detail of 11 000 bytes still arrives and from 12 000 bytes the client getsh2 protocol errorwith no details at all. The error trailers are therefore kept withinMAX_ERROR_TRAILER_BYTES= 8 KiB, the metadata size gRPC clients accept by default (grpc-java'smaxInboundMetadataSizeon Netty, which fails the RPC above 8192; C-core's softgrpc.max_metadata_size, above which RPCs are rejected at random up to the 16 KB hard limit; the limit grpc-go is moving to), measured as HTTP/2 counts a header list (RFC 9113 §6.5.2: name + value + 32 per field).trailer_bytesruns tonic's ownStatus::into_httpon the candidate status, socontent-type,grpc-status, the percent-encodedgrpc-messageand the base64grpc-status-details-binare counted as tonic sends them, and adds the two fields tonic does not write::status(RFC 9113 §8.3.2) anddate(RFC 9110 §6.6.1, added by hyper). The message,ErrorInfoandBadRequestalways go; the first Struct detail that does not fit and the ones after it are dropped with atracing::warn!, and the client still receives the error. grpc-go and grpc-java check the peer's advertisedSETTINGS_MAX_HEADER_LIST_SIZEwhen sending; a tonic service cannot see it, so the default is the budget. TheTypedDetailrustdoc ina2anow says that gRPC may drop details that do not fit, so an agent author learns it before the warning does.This limit is a property of gRPC, not of this crate (grpc.io, Error handling: "Larger error detail payloads may run into protocol limits (like max headers size), effectively losing the original error"), and the specification does not mention it; a2a-go sends every detail with no budget and a2a-python sends none but
ErrorInfoandBadRequest. I raised that in a2aproject/A2A#2433 with the sources and an SDK table; this PR is a draft until there is an answer on how the bindings should agree (see the comment below).Tests
test_struct_details_round_trip_through_a_grpc_status: a Struct detail survivesa2a_error_to_status→status_to_a2a_errorunchanged (fails onmain: only theErrorInfocomes back).test_error_info_and_bad_request_stay_first_on_the_wire: the rawgoogle.rpc.StatuslistsErrorInfo,BadRequest,Structin that order even when the error lists the Struct first (fails onmain).test_details_of_other_types_are_not_sent_as_structs: aRetryInfodetail does not reach the client as aStruct; only theErrorInfodoes (passes onmain, guards the choice above).test_status_without_other_details_is_unchanged: an error with onlyErrorInfoandBadRequestproduces the same details bytes astonic::Status::with_error_details(passes onmain, guards the existing encoding).test_error_trailers_stay_within_the_default_grpc_metadata_limit: small, over-limit, small; only the first small detail survives and the trailers stay within 8 KiB.test_the_message_counts_against_the_trailer_budget: a long message keeps its place and the detail is dropped instead.test_trailer_bytes_counts_fields_as_http2_does: the accounting matches tonic's encoding ofcontent-type,grpc-status,grpc-messageandgrpc-status-details-bin.grpc_transport_receives_struct_details_from_a_real_server: a real tonic server returns the Struct detail toGrpcTransport(fails onmain).grpc_transport_still_receives_an_error_whose_detail_is_too_large: a 64 KiB detail; the client gets the code, the message and theErrorInfo(without the cap the client gets an h2 protocol error and nothing else).CI mirror (
ci.ymlon Linux): fmt,cargo hack check/clippy --each-feature -D warnings, headers, 977 tests passed. Patch coverage ascoverage.ymlcomputes it: 189 added lines, 0 missed.Overlap
Touches
a2a-grpc/src/errors.rs,a2a-grpc/tests/e2e.rsand four doc lines ina2a/src/errordetails.rs. No overlap with the open A2A 1.1 stack. Based onmainat 505dbad.🤖 Generated with Claude Code