fix: Use POST method for REST endpoint /tasks/{id}:subscribe

[bartek-w]

POST should be always use for /tasks/{id}:subscribe.
Decisions for backward compatibility with invalid protocol implementations:
1.0 server: Accept both POST and GET
1.0 client: Always use POST
0.3 server: Accept both POST and GET
0.3 client: Try POST first, on HTTP 405 error retry with GET. Cache the retry state to ensure that there is at most one retry attempt per transport instance.

Fixes #840

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request standardizes the /tasks/{id}:subscribe endpoint to primarily use the POST method, which is more appropriate for operations that involve sending data in the request body. It introduces robust backward compatibility mechanisms, allowing both newer and older clients and servers to interact seamlessly without breaking existing integrations. The changes ensure that the system is more resilient to varying client behaviors and server configurations, while also improving the robustness of error handling for HTTP responses.

Highlights

• Standardized Subscription Method: The /tasks/{id}:subscribe endpoint now consistently uses the POST method across both client and server implementations for version 1.0, aligning with REST best practices for operations that send data in the request body.
• Backward Compatibility for v0.3 Clients: Version 0.3 clients are updated to first attempt a POST request for task subscriptions and gracefully fall back to a GET request if a 405 Method Not Allowed error is received, caching this preference for subsequent calls on the same transport instance.
• Backward Compatibility for v0.3 Servers: Version 0.3 servers are configured to accept both POST and GET requests for the /v1/tasks/{id}:subscribe endpoint, ensuring compatibility with older clients that might still use GET.
• Robust Error Handling: Improved error handling in the v0.3 REST transport to prevent crashes when encountering non-JSON error responses from the server by gracefully handling JSON decoding failures.
• Request Body Parsing: The server-side handler for task subscriptions now correctly parses the request body for POST requests, allowing subscription parameters to be sent in the request payload.

Changelog

• src/a2a/client/transports/rest.py
  • Changed the subscribe method to use 'POST' instead of 'GET' for the /tasks/{id}:subscribe endpoint.
  • Added json=MessageToDict(request) to the _send_stream_request call to send the request body.
• src/a2a/compat/v0_3/rest_adapter.py
  • Added a route to handle 'POST' requests for /v1/tasks/{id}:subscribe by mapping it to on_subscribe_to_task.
• src/a2a/compat/v0_3/rest_transport.py
  • Initialized _subscribe_method to 'POST' and _subscribe_retry_attempted to False for retry logic.
  • Implemented retry logic in the subscribe method: it now attempts 'POST' first, falls back to 'GET' on a 405 error, and caches the method preference.
  • Enhanced _handle_http_error to catch json.JSONDecodeError, ValueError, and httpx.ResponseNotRead when parsing error responses, defaulting to an empty dictionary if JSON decoding fails.
• src/a2a/server/apps/rest/rest_adapter.py
  • Added a route to handle 'POST' requests for /tasks/{id}:subscribe by mapping it to on_subscribe_to_task.
• src/a2a/server/request_handlers/rest_handler.py
  • Modified on_subscribe_to_task to parse the request body for SubscribeToTaskRequest parameters when the request method is 'POST'.
• tests/client/transports/test_rest_client.py
  • Updated the test_streaming_client_methods test to assert that the subscribe method uses 'POST' and sends the request object as JSON.
• tests/compat/v0_3/test_rest_handler.py
  • Added test_on_subscribe_to_task_post to verify that the on_subscribe_to_task handler correctly processes POST requests with a body.
• tests/compat/v0_3/test_rest_transport.py
  • Added helper functions create_405_error and create_500_error for testing error scenarios.
  • Added test_compat_rest_transport_subscribe_post_works_no_retry to confirm POST works without retry.
  • Added test_compat_rest_transport_subscribe_post_405_retry_get_success to test the POST-to-GET retry mechanism on 405.
  • Added test_compat_rest_transport_subscribe_post_405_get_405_fails to test failure when both POST and GET return 405.
  • Added test_compat_rest_transport_subscribe_post_500_no_retry to ensure no retry occurs on 500 errors.
• tests/server/apps/rest/test_rest_fastapi_app.py
  • Updated the agent_card fixture to enable streaming capabilities.
  • Added test_subscribe_to_task_get to verify GET requests to /tasks/{id}:subscribe.
  • Added test_subscribe_to_task_post to verify POST requests to /tasks/{id}:subscribe with a request body.
  • Modified configure_mocks to set a default mock for on_subscribe_to_task.
  • Added new test cases for test_tenant_extraction to include GET and POST for /tasks/1:subscribe.

Activity

• Resolved issue [Bug]: REST /tasks/{id}:subscribe uses GET method instead of POST #840.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[github-actions]

🧪 Code Coverage (vs 1.0-dev)

⬇️ Download Full Report

No coverage changes.

Generated by coverage-comment.yml

[gemini-code-assist]

Code Review

This pull request correctly updates the /tasks/{id}:subscribe endpoint to use the POST method, aligning with REST principles. The changes include backward compatibility for older protocol versions, allowing servers to accept both GET and POST, and implementing a retry mechanism in the v0.3 client. The implementation is well-tested, covering various scenarios including the new retry logic. I've identified one potential bug in the v0.3 client implementation and a small improvement for one of the tests.

[ishymko]

Thank you for this! Feel free to follow-up on comments via a separate PR. This should be good for alpha.0

[ishymko]

LGTM, but linter is unhappy.