Skip to content

Commit 6ff0a82

Browse files
ftnextmykytanetipa
andauthored
feat: allow configuring SSE shutdown grace periods (a2aproject#1222)
- [x] Follow the [`CONTRIBUTING` Guide](https://github.com/a2aproject/a2a-python/blob/main/CONTRIBUTING.md). - [x] Make your Pull Request title in the <https://www.conventionalcommits.org/> specification. - [x] Ensure the tests and linter pass (Run `bash scripts/format.sh` from the repository root to format) - [ ] Appropriate docs were updated (if necessary) --- # Description Adds an optional `shutdown_grace_period` parameter to the JSON-RPC and REST route factories and forwards it to every `EventSourceResponse`, including the v0.3 compatibility routes. The default remains `0` for backward compatibility with `sse-starlette`. The minimum supported `sse-starlette` version is updated to `3.3.0`, where cooperative shutdown support was introduced. Tests cover: - Default and custom values for both route factories - JSON-RPC and REST streaming responses - JSON-RPC and REST v0.3 compatibility routes - Empty REST streams ## Verification - [x] `./scripts/lint.sh` - [x] `uv run pytest` - [x] `uv run pytest --cov=src --cov-report=term-missing` - [x] 93% total coverage Fixes a2aproject#1221 🦕 --------- Co-authored-by: mykytanetipa <mykytanetipa@google.com>
1 parent 52030cf commit 6ff0a82

14 files changed

Lines changed: 352 additions & 15 deletions

‎src/a2a/compat/v0_3/jsonrpc_adapter.py‎

Lines changed: 8 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -39,6 +39,7 @@
3939
from a2a.server.routes.common import (
4040
DefaultServerCallContextBuilder,
4141
ServerCallContextBuilder,
42+
create_event_source_response,
4243
)
4344
from a2a.utils import constants
4445
from a2a.utils.version_validator import validate_version
@@ -67,13 +68,15 @@ def __init__(
6768
self,
6869
http_handler: 'RequestHandler',
6970
context_builder: 'ServerCallContextBuilder | None' = None,
70-
):
71+
shutdown_grace_period: float = 0,
72+
) -> None:
7173
self.handler = RequestHandler03(
7274
request_handler=http_handler,
7375
)
7476
self._context_builder = V03ServerCallContextBuilder(
7577
context_builder or DefaultServerCallContextBuilder()
7678
)
79+
self._shutdown_grace_period = shutdown_grace_period
7780

7881
def supports_method(self, method: str) -> bool:
7982
"""Returns True if the v0.3 adapter supports the given method name."""
@@ -277,4 +280,7 @@ async def event_generator(
277280
)
278281
}
279282

280-
return EventSourceResponse(event_generator(stream_gen))
283+
return create_event_source_response(
284+
event_generator(stream_gen),
285+
shutdown_grace_period=self._shutdown_grace_period,
286+
)

‎src/a2a/compat/v0_3/rest_adapter.py‎

Lines changed: 7 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,7 @@
3535
from a2a.server.routes.common import (
3636
DefaultServerCallContextBuilder,
3737
ServerCallContextBuilder,
38+
create_event_source_response,
3839
)
3940
from a2a.utils import json_utils
4041
from a2a.utils.error_handlers import (
@@ -59,11 +60,13 @@ def __init__(
5960
self,
6061
http_handler: 'RequestHandler',
6162
context_builder: 'ServerCallContextBuilder | None' = None,
62-
):
63+
shutdown_grace_period: float = 0,
64+
) -> None:
6365
self.handler = REST03Handler(request_handler=http_handler)
6466
self._context_builder = V03ServerCallContextBuilder(
6567
context_builder or DefaultServerCallContextBuilder()
6668
)
69+
self._shutdown_grace_period = shutdown_grace_period
6770

6871
@rest_error_handler
6972
async def _handle_request(
@@ -96,8 +99,9 @@ async def event_generator(
9699
async for item in stream:
97100
yield json_utils.dumps(item)
98101

99-
return EventSourceResponse(
100-
event_generator(method(request, call_context))
102+
return create_event_source_response(
103+
event_generator(method(request, call_context)),
104+
shutdown_grace_period=self._shutdown_grace_period,
101105
)
102106

103107
def routes(self) -> dict[tuple[str, str], Callable[[Request], Any]]:

‎src/a2a/server/routes/common.py‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
11
from abc import ABC, abstractmethod
2+
from inspect import signature
23
from typing import TYPE_CHECKING, Any
34

45
from google.protobuf.json_format import MessageToDict
@@ -7,13 +8,16 @@
78

89

910
if TYPE_CHECKING:
11+
from sse_starlette.sse import EventSourceResponse
1012
from starlette.authentication import BaseUser
1113
from starlette.requests import Request
1214
else:
1315
try:
16+
from sse_starlette.sse import EventSourceResponse
1417
from starlette.authentication import BaseUser
1518
from starlette.requests import Request
1619
except ImportError:
20+
EventSourceResponse = Any
1721
Request = Any
1822
BaseUser = Any
1923

@@ -40,6 +44,33 @@ def serialize_list_tasks_response(
4044
return result
4145

4246

47+
def create_event_source_response(
48+
content: Any,
49+
shutdown_grace_period: float = 0,
50+
) -> 'EventSourceResponse':
51+
"""Creates an SSE response, preserving support for older sse-starlette.
52+
53+
A non-zero grace period requires cooperative shutdown support from
54+
sse-starlette, provided by the HTTP server optional dependencies.
55+
"""
56+
if shutdown_grace_period < 0:
57+
raise ValueError('shutdown_grace_period must be >= 0')
58+
if shutdown_grace_period:
59+
if (
60+
'shutdown_grace_period'
61+
not in signature(EventSourceResponse.__init__).parameters
62+
):
63+
raise RuntimeError(
64+
'Configuring shutdown_grace_period requires sse-starlette with '
65+
'cooperative shutdown support. Upgrade the dependencies for '
66+
'a2a-sdk[http-server].'
67+
)
68+
return EventSourceResponse(
69+
content, shutdown_grace_period=shutdown_grace_period
70+
)
71+
return EventSourceResponse(content)
72+
73+
4374
class StarletteUser(User):
4475
"""Adapts a Starlette BaseUser to the A2A User interface."""
4576

‎src/a2a/server/routes/jsonrpc_dispatcher.py‎

Lines changed: 12 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44
import logging
55

66
from collections.abc import AsyncGenerator
7-
from typing import TYPE_CHECKING, Any
7+
from typing import TYPE_CHECKING, Any, cast
88

99
from google.protobuf.json_format import MessageToDict, ParseDict
1010
from jsonrpc.jsonrpc2 import JSONRPC20Request, JSONRPC20Response
@@ -23,6 +23,7 @@
2323
from a2a.server.routes.common import (
2424
DefaultServerCallContextBuilder,
2525
ServerCallContextBuilder,
26+
create_event_source_response,
2627
serialize_list_tasks_response,
2728
)
2829
from a2a.types.a2a_pb2 import (
@@ -129,6 +130,7 @@ def __init__(
129130
request_handler: RequestHandler,
130131
context_builder: ServerCallContextBuilder | None = None,
131132
enable_v0_3_compat: bool = False,
133+
shutdown_grace_period: float = 0,
132134
) -> None:
133135
"""Initializes the JsonRpcDispatcher.
134136
@@ -139,6 +141,8 @@ def __init__(
139141
ServerCallContext passed to the request_handler. If None the
140142
DefaultServerCallContextBuilder is used.
141143
enable_v0_3_compat: Whether to enable v0.3 backward compatibility on the same endpoint.
144+
shutdown_grace_period: Seconds to allow active SSE streams to
145+
finish before force-cancellation during shutdown.
142146
"""
143147
if not _package_starlette_installed:
144148
raise ImportError(
@@ -152,12 +156,14 @@ def __init__(
152156
context_builder or DefaultServerCallContextBuilder()
153157
)
154158
self.enable_v0_3_compat = enable_v0_3_compat
159+
self._shutdown_grace_period = shutdown_grace_period
155160
self._v03_adapter: JSONRPC03Adapter | None = None
156161

157162
if self.enable_v0_3_compat:
158163
self._v03_adapter = JSONRPC03Adapter(
159164
http_handler=request_handler,
160165
context_builder=self._context_builder,
166+
shutdown_grace_period=shutdown_grace_period,
161167
)
162168

163169
def _generate_error_response(
@@ -596,7 +602,11 @@ async def event_generator(
596602
'data': json_utils.dumps(error_response),
597603
}
598604

599-
return EventSourceResponse(event_generator(handler_result)) # ty:ignore[invalid-argument-type]
605+
stream = cast('AsyncGenerator[dict[str, Any]]', handler_result)
606+
return create_event_source_response(
607+
event_generator(stream),
608+
shutdown_grace_period=self._shutdown_grace_period,
609+
)
600610

601611
# handler_result is a dict (JSON-RPC response)
602612
return JSONResponse(handler_result)

‎src/a2a/server/routes/jsonrpc_routes.py‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,7 @@ def create_jsonrpc_routes(
3030
rpc_url: str,
3131
context_builder: ServerCallContextBuilder | None = None,
3232
enable_v0_3_compat: bool = False,
33+
shutdown_grace_period: float = 0,
3334
) -> list['Route']:
3435
"""Creates the Starlette Route for the A2A protocol JSON-RPC endpoint.
3536
@@ -45,6 +46,10 @@ def create_jsonrpc_routes(
4546
ServerCallContext passed to the request_handler. If None the
4647
DefaultServerCallContextBuilder is used.
4748
enable_v0_3_compat: Whether to enable v0.3 backward compatibility on the same endpoint.
49+
shutdown_grace_period: Seconds to allow active SSE streams to finish
50+
before force-cancellation during shutdown. This value should be less
51+
than the ASGI server's graceful shutdown timeout. Defaults to 0,
52+
matching the ``sse-starlette`` default behavior.
4853
"""
4954
if not _package_starlette_installed:
5055
raise ImportError(
@@ -57,6 +62,7 @@ def create_jsonrpc_routes(
5762
request_handler=request_handler,
5863
context_builder=context_builder,
5964
enable_v0_3_compat=enable_v0_3_compat,
65+
shutdown_grace_period=shutdown_grace_period,
6066
)
6167

6268
return [

‎src/a2a/server/routes/rest_dispatcher.py‎

Lines changed: 13 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,7 @@
1010
from a2a.server.routes.common import (
1111
DefaultServerCallContextBuilder,
1212
ServerCallContextBuilder,
13+
create_event_source_response,
1314
serialize_list_tasks_response,
1415
)
1516
from a2a.types import a2a_pb2
@@ -78,6 +79,7 @@ def __init__(
7879
self,
7980
request_handler: RequestHandler,
8081
context_builder: ServerCallContextBuilder | None = None,
82+
shutdown_grace_period: float = 0,
8183
) -> None:
8284
"""Initializes the RestDispatcher.
8385
@@ -86,6 +88,8 @@ def __init__(
8688
context_builder: The ServerCallContextBuilder used to construct the
8789
ServerCallContext passed to the request_handler. If None the
8890
DefaultServerCallContextBuilder is used.
91+
shutdown_grace_period: Seconds to allow active SSE streams to
92+
finish before force-cancellation during shutdown.
8993
"""
9094
if not _package_starlette_installed:
9195
raise ImportError(
@@ -98,6 +102,7 @@ def __init__(
98102
context_builder or DefaultServerCallContextBuilder()
99103
)
100104
self.request_handler = request_handler
105+
self._shutdown_grace_period = shutdown_grace_period
101106

102107
def _build_call_context(self, request: Request) -> ServerCallContext:
103108
call_context = self._context_builder.build(request)
@@ -143,7 +148,10 @@ async def _handle_streaming(
143148
try:
144149
first_item = await anext(stream)
145150
except StopAsyncIteration:
146-
return EventSourceResponse(iter([]))
151+
return create_event_source_response(
152+
iter([]),
153+
shutdown_grace_period=self._shutdown_grace_period,
154+
)
147155

148156
async def event_generator() -> AsyncIterator[ServerSentEvent]:
149157
yield ServerSentEvent(data=json_utils.dumps(first_item))
@@ -157,7 +165,10 @@ async def event_generator() -> AsyncIterator[ServerSentEvent]:
157165
event='error',
158166
)
159167

160-
return EventSourceResponse(event_generator())
168+
return create_event_source_response(
169+
event_generator(),
170+
shutdown_grace_period=self._shutdown_grace_period,
171+
)
161172

162173
@rest_error_handler
163174
async def on_message_send(self, request: Request) -> Response:

‎src/a2a/server/routes/rest_routes.py‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,7 @@ def create_rest_routes(
3232
context_builder: ServerCallContextBuilder | None = None,
3333
enable_v0_3_compat: bool = False,
3434
path_prefix: str = '',
35+
shutdown_grace_period: float = 0,
3536
) -> list['BaseRoute']:
3637
"""Creates the Starlette Routes for the A2A protocol REST endpoint.
3738
@@ -44,6 +45,10 @@ def create_rest_routes(
4445
enable_v0_3_compat: If True, mounts backward-compatible v0.3 protocol
4546
endpoints using REST03Adapter.
4647
path_prefix: The URL prefix for the REST endpoints.
48+
shutdown_grace_period: Seconds to allow active SSE streams to finish
49+
before force-cancellation during shutdown. This value should be less
50+
than the ASGI server's graceful shutdown timeout. Defaults to 0,
51+
matching the ``sse-starlette`` default behavior.
4752
"""
4853
if not _package_starlette_installed:
4954
raise ImportError(
@@ -55,13 +60,15 @@ def create_rest_routes(
5560
dispatcher = RestDispatcher(
5661
request_handler=request_handler,
5762
context_builder=context_builder,
63+
shutdown_grace_period=shutdown_grace_period,
5864
)
5965

6066
routes: list[BaseRoute] = []
6167
if enable_v0_3_compat:
6268
v03_adapter = REST03Adapter(
6369
http_handler=request_handler,
6470
context_builder=context_builder,
71+
shutdown_grace_period=shutdown_grace_period,
6572
)
6673
v03_routes = v03_adapter.routes()
6774
for (path, method), endpoint in v03_routes.items():

‎tests/compat/v0_3/test_jsonrpc_app_compat.py‎

Lines changed: 34 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,13 @@
11
import logging
22

3-
from unittest.mock import AsyncMock
3+
from collections.abc import AsyncIterator
4+
from unittest.mock import AsyncMock, MagicMock, patch
45

56
import pytest
67

8+
from a2a.compat.v0_3 import jsonrpc_adapter
9+
from a2a.compat.v0_3.jsonrpc_adapter import JSONRPC03Adapter
10+
from a2a.server.context import ServerCallContext
711
from a2a.server.request_handlers.request_handler import RequestHandler
812
from a2a.server.routes import create_jsonrpc_routes
913
from a2a.types.a2a_pb2 import (
@@ -23,6 +27,35 @@
2327
logger = logging.getLogger(__name__)
2428

2529

30+
@pytest.mark.asyncio
31+
async def test_shutdown_grace_period_is_passed_to_event_source_response(
32+
mock_handler: AsyncMock,
33+
) -> None:
34+
async def stream_generator() -> AsyncIterator[MagicMock]:
35+
yield MagicMock()
36+
37+
adapter = JSONRPC03Adapter(
38+
http_handler=mock_handler,
39+
shutdown_grace_period=30.0,
40+
)
41+
adapter.handler.on_message_send_stream = MagicMock(
42+
return_value=stream_generator()
43+
)
44+
request_obj = MagicMock(method='message/stream')
45+
46+
with patch.object(
47+
jsonrpc_adapter, 'create_event_source_response'
48+
) as response_class:
49+
await adapter._process_streaming_request(
50+
request_id='1',
51+
request_obj=request_obj,
52+
context=ServerCallContext(),
53+
)
54+
55+
response_class.assert_called_once()
56+
assert response_class.call_args.kwargs['shutdown_grace_period'] == 30.0
57+
58+
2659
@pytest.fixture
2760
def mock_handler():
2861
handler = AsyncMock(spec=RequestHandler)

0 commit comments

Comments
 (0)