Repository navigation
fix(server): answer HEAD on GET routes mounted on FastAPI - #1472
Closed
saquibjawedbit wants to merge 2 commits into
Closed
saquibjawedbit wants to merge 2 commits into
saquibjawedbit wants to merge 2 commits into
Conversation
The Starlette route factories answer HEAD for every GET route, but
add_a2a_routes_to_fastapi does not. It re-registers each route as a
FastAPI APIRoute without HEAD, to avoid duplicate operation IDs in
/docs, and APIRoute does not add HEAD back for a GET route. HEAD on the
agent card or on GET /tasks/{id} therefore stopped working once the
routes were mounted on FastAPI, including the cheap ETag revalidation
of the agent card.
Keep the original route mounted behind the APIRoute. It is not an
APIRoute, so it stays out of the OpenAPI schema, and it serves HEAD as
it does on Starlette.
🧪 Code Coverage (vs
|
| Base | PR | Delta | |
|---|---|---|---|
| src/a2a/server/routes/fastapi_routes.py | 91.89% | 92.31% | 🟢 +0.42% |
| Total | 93.63% | 93.63% | ⚪️ 0.00% |
Generated by coverage-comment.yml
Member
|
Thanks for the detailed writeup and the repro. We're not going to merge this one. The spec doesn't mention HEAD anywhere, and the current 405 matches what a2a-go does You're right that Starlette answers HEAD by default. But that's a property of the library we happen to mount on, not a decision about where the SDK is going If you think that HEAD should be supported, then please raise it in the A2A spec repo so all the SDKs move together. Thanks again. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
The SDK's Starlette route factories answer
HEADon every GET route, butadd_a2a_routes_to_fastapidoes not. Once the routes are mounted on FastAPI,HEADon the agent card and onGET /tasks/{id}stops working. This also breaks the cheap way to revalidate the agent card: since #1272 the card is served withETagandCache-Control, and a client or cache can check those headers withHEADwithout downloading the card. RFC 9110 §9.1 says general-purpose servers MUST supportGETandHEAD.With the REST routes mounted as well, the same request returns 404 instead. That 404 comes from the helper's own route order: with no route left to answer
HEAD, the request falls into the/{tenant}mount, which reads.well-knownas a tenant. This PR does not change the tenant mount or how routes are matched (the subject of #1443). It only givesHEADa route to land on again.The cause is in
_attach_route. Since #1024 it dropsHEADwhen it rebuilds each route as anAPIRoute, so that/docsdoes not get duplicate operation IDs. Unlike Starlette'sRoute,APIRoutedoes not addHEADback for a GET route, so nothing answers it any more.Fix
When the original route accepts
HEAD,_attach_routenow also appends that route after theAPIRoute.GETstill matches theAPIRoutefirst. ForHEADtheAPIRoutematches only partly (wrong method), so the router moves on to the original route, which answers it as it does on Starlette. The original route is not anAPIRoute, so FastAPI leaves it out of the schema, and/docsstill has no HEAD operations.Testing evidence
New test
test_get_routes_still_answer_headintests/server/routes/test_fastapi_routes.py. It checks that:HEADon the agent card returns 200 with an empty body and the sameETagasGET.HEAD /tasks/{id}returns 200 with an empty body and calls the handler once.headoperation for either path.HEADwith 200.Before the fix (
src/a2a/server/routes/fastapi_routes.pyfrommainatcaab6a2):After the fix:
./scripts/lint.sh: ruff check and ruff format pass (285 files unchanged), and so does ty. ty prints the same 3 unusedtype: ignorewarnings as onmain, in files this PR does not touch.uv run pytest --cov=src --cov-report=term-missing: 2618 passed, 215 skipped, 4 xfailed, 1 xpassed, 4 errors, 94% total coverage. The 4 errors are intests/integration/cross_version/client_server/test_client_server.py: the v0.3 test server does not start in time on my machine.maingives the same 4 errors.Follow the
CONTRIBUTINGGuide.Make your Pull Request title in the https://www.conventionalcommits.org/ specification.
Ensure the tests and linter pass (Run
bash scripts/format.shfrom the repository root to format)Appropriate docs were updated (if necessary)