Skip to content

Commit 6168d59

Browse files
authored
feat(cluster): Introduce ServerCallContext to DatabaseTaskEventStream (#1399)
# Enabling ServerCallContext in DatabaseTaskEventStream methods closes #1374 ## Change This PR adds `context` to `DatabaseTaskEventStream` methods: `subscribe`, `publish`, `destroy` To keep it backward-compatible, it doesen't change `TaskEventStream` abstract class. Instead, `DefaultRequestHandler` and activetask `EventConsumer` check if methods of current `TaskEventStream` instance support `context` arg; otherwise, they warn. Also, `_seq_at_or_before_version` method adds `owner` condition to follow `TaskStore` ownership behaviour In long-term, the `TaskEventStream` methods should include `context` arg (breaking change, #1398) ## Tests Added 3 tests - Ensuring that warnings are logged when using `TaskEventStream` instance, that owner is accepted and that owner can't see other owner events
1 parent 43d1eff commit 6168d59

5 files changed

Lines changed: 265 additions & 33 deletions

File tree

‎src/a2a/server/agent_execution/active_task.py‎

Lines changed: 15 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -57,7 +57,10 @@
5757
)
5858
from a2a.server.tasks.task_manager import TaskManager
5959

60-
from a2a.server.cluster.event_stream import VersionedEvent
60+
from a2a.server.cluster.event_stream import (
61+
VersionedEvent,
62+
_stream_accepts_context,
63+
)
6164
from a2a.server.cluster.task_store import ConcurrentTaskModificationError
6265
from a2a.server.events.event_queue_v2 import (
6366
AsyncQueue,
@@ -435,10 +438,17 @@ async def _enqueue_to_subscribers(
435438
stream = self.active_task._event_stream
436439
if stream is not None and isinstance(event, Event):
437440
version = self.active_task._task_manager.current_version
438-
await stream.publish(
439-
self.active_task._task_id,
440-
VersionedEvent(event=event, version=version),
441-
)
441+
versioned_event = VersionedEvent(event=event, version=version)
442+
task_id = self.active_task._task_id
443+
if _stream_accepts_context(stream, 'publish'):
444+
# TODO(ISSUE #1374): remove this check once ServerCallContext is a required parameter on TaskEventStream.
445+
await stream.publish(
446+
task_id,
447+
versioned_event,
448+
context=self.active_task._task_manager._call_context, # ty:ignore[unknown-argument]
449+
)
450+
else:
451+
await stream.publish(task_id, versioned_event)
442452

443453
self.active_task._event_queue_agent.task_done()
444454

‎src/a2a/server/cluster/database_event_stream.py‎

Lines changed: 51 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -25,8 +25,14 @@
2525

2626
from a2a.server.cluster.event_stream import TaskEventStream, VersionedEvent
2727
from a2a.server.cluster.version import TaskVersion
28+
from a2a.server.context import ServerCallContext
2829
from a2a.server.events.event_queue import Event
29-
from a2a.server.models import Base, TaskEventModel, create_task_event_model
30+
from a2a.server.models import (
31+
Base,
32+
TaskEventModel,
33+
create_task_event_model,
34+
)
35+
from a2a.server.owner_resolver import OwnerResolver
3036
from a2a.types.a2a_pb2 import StreamResponse
3137

3238

@@ -64,20 +70,23 @@ class DatabaseTaskEventStream(TaskEventStream):
6470
"""`TaskEventStream` backed by polling the shared ``task_events`` table."""
6571

6672
_event_model: type[TaskEventModel]
73+
owner_resolver: OwnerResolver | None
6774

6875
def __init__(
6976
self,
7077
engine: AsyncEngine,
7178
create_table: bool = True,
7279
table_name: str = 'task_events',
7380
poll_interval_s: float = _DEFAULT_POLL_INTERVAL_S,
81+
owner_resolver: OwnerResolver | None = None,
7482
) -> None:
7583
"""Initializes the stream over an existing SQLAlchemy AsyncEngine."""
7684
self._engine = engine
7785
self._session_maker = async_sessionmaker(engine, expire_on_commit=False)
7886
self._create_table = create_table
7987
self._poll_interval_s = poll_interval_s
8088
self._initialized = False
89+
self.owner_resolver = owner_resolver
8190
self._event_model = ( # ty:ignore[invalid-assignment]
8291
TaskEventModel
8392
if table_name == 'task_events'
@@ -99,55 +108,75 @@ async def _ensure_initialized(self) -> None:
99108
if not self._initialized:
100109
await self.initialize()
101110

102-
async def publish(self, task_id: str, event: VersionedEvent) -> None:
111+
async def publish(
112+
self,
113+
task_id: str,
114+
event: VersionedEvent,
115+
context: ServerCallContext | None = None,
116+
) -> None:
103117
"""No-op: events are persisted transactionally by the task store."""
104-
del task_id, event
118+
del task_id, event, context
105119

106120
async def _seq_at_or_before_version(
107-
self, session: AsyncSession, task_id: str, after: TaskVersion
121+
self,
122+
session: AsyncSession,
123+
task_id: str,
124+
after: TaskVersion,
125+
owner: str | None,
108126
) -> int:
109127
"""Seq to start polling from so nothing after `after` is missed."""
110128
if after.is_missing:
111129
return 0
130+
conditions = [
131+
self._event_model.task_id == task_id,
132+
self._event_model.task_version <= _as_int(after),
133+
]
134+
if owner is not None:
135+
conditions.append(self._event_model.owner == owner)
112136
stmt = (
113137
select(self._event_model.seq)
114-
.where(
115-
and_(
116-
self._event_model.task_id == task_id,
117-
self._event_model.task_version <= _as_int(after),
118-
)
119-
)
138+
.where(and_(*conditions))
120139
.order_by(self._event_model.seq.desc())
121140
.limit(1)
122141
)
123142
result = (await session.execute(stmt)).scalar_one_or_none()
124143
return result or 0
125144

126145
async def subscribe( # type: ignore[override]
127-
self, task_id: str, *, after: TaskVersion
146+
self,
147+
task_id: str,
148+
*,
149+
after: TaskVersion,
150+
context: ServerCallContext | None = None,
128151
) -> AsyncGenerator[VersionedEvent, None]:
129152
"""Polls the log for events of `task_id` newer than `after`."""
130153
await self._ensure_initialized()
154+
owner = (
155+
self.owner_resolver(context or ServerCallContext())
156+
if self.owner_resolver is not None
157+
else None
158+
)
131159
async with self._session_maker() as session:
132160
cursor = await self._seq_at_or_before_version(
133-
session, task_id, after
161+
session, task_id, after, owner
134162
)
135163

136164
while True:
137165
try:
138166
async with self._session_maker() as session:
167+
conditions = [
168+
self._event_model.task_id == task_id,
169+
self._event_model.seq > cursor,
170+
]
171+
if owner is not None:
172+
conditions.append(self._event_model.owner == owner)
139173
stmt = (
140174
select(
141175
self._event_model.seq,
142176
self._event_model.task_version,
143177
self._event_model.event_data,
144178
)
145-
.where(
146-
and_(
147-
self._event_model.task_id == task_id,
148-
self._event_model.seq > cursor,
149-
)
150-
)
179+
.where(and_(*conditions))
151180
.order_by(self._event_model.seq.asc())
152181
)
153182
rows = (await session.execute(stmt)).all()
@@ -176,6 +205,8 @@ async def subscribe( # type: ignore[override]
176205
if not rows:
177206
await asyncio.sleep(self._poll_interval_s)
178207

179-
async def destroy(self, task_id: str) -> None:
208+
async def destroy(
209+
self, task_id: str, context: ServerCallContext | None = None
210+
) -> None:
180211
"""No-op: the append-only log is retained; subscribers stop on their own."""
181-
del task_id
212+
del task_id, context

‎src/a2a/server/cluster/event_stream.py‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,7 @@
1+
import inspect
2+
import logging
3+
import warnings
4+
15
from abc import ABC, abstractmethod
26
from collections.abc import AsyncGenerator
37
from dataclasses import dataclass
@@ -6,6 +10,9 @@
610
from a2a.server.events.event_queue import Event
711

812

13+
logger = logging.getLogger(__name__)
14+
15+
916
@dataclass(frozen=True)
1017
class VersionedEvent:
1118
"""An event together with the task version produced by applying it."""
@@ -30,3 +37,38 @@ def subscribe(
3037
@abstractmethod
3138
async def destroy(self, task_id: str) -> None:
3239
"""Releases resources for a task that has reached a terminal state."""
40+
41+
42+
_context_support_cache: dict[tuple[type, str], bool] = {}
43+
44+
45+
def _stream_accepts_context(stream: TaskEventStream, method_name: str) -> bool:
46+
"""Temporary solution to support ServerCallContext being passed to TaskEventStream.
47+
48+
Checks if given method of TaskEventStream accepts context parameter.
49+
If not, it logs a warning and returns False.
50+
51+
TODO(ISSUE #1374): remove this function once ServerCallContext is a required parameter on TaskEventStream.
52+
"""
53+
key = (type(stream), method_name)
54+
cached = _context_support_cache.get(key)
55+
if cached is not None:
56+
return cached
57+
58+
params = inspect.signature(getattr(stream, method_name)).parameters
59+
accepts = 'context' in params or any(
60+
p.kind is p.VAR_KEYWORD for p in params.values()
61+
)
62+
_context_support_cache[key] = accepts
63+
64+
if not accepts:
65+
message = (
66+
f'{type(stream).__name__}.{method_name} does not accept a '
67+
"'context' parameter; ownership checks are skipped for this "
68+
'TaskEventStream implementation. This will become a required '
69+
'parameter in a future major version.'
70+
)
71+
warnings.warn(message, DeprecationWarning, stacklevel=3)
72+
logger.warning(message)
73+
74+
return accepts

‎src/a2a/server/request_handlers/default_request_handler_v2.py‎

Lines changed: 27 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,10 @@
1919
from a2a.server.agent_execution.plugin_agent_executor import (
2020
PluginAgentExecutor,
2121
)
22-
from a2a.server.cluster.event_stream import VersionedEvent
22+
from a2a.server.cluster.event_stream import (
23+
VersionedEvent,
24+
_stream_accepts_context,
25+
)
2326
from a2a.server.cluster.task_store import (
2427
ConcurrentTaskModificationError,
2528
LegacyTaskStoreAdapter,
@@ -375,9 +378,16 @@ async def _write_cancel(
375378
)
376379
)
377380
if self._event_stream is not None:
378-
await self._event_stream.publish(
379-
task_id, VersionedEvent(event=event, version=new_version)
380-
)
381+
versioned_event = VersionedEvent(event=event, version=new_version)
382+
if _stream_accepts_context(self._event_stream, 'publish'):
383+
# TODO(ISSUE #1374): remove this check once ServerCallContext is a required parameter on TaskEventStream.
384+
await self._event_stream.publish(
385+
task_id,
386+
versioned_event,
387+
context=context, # ty:ignore[unknown-argument]
388+
)
389+
else:
390+
await self._event_stream.publish(task_id, versioned_event)
381391
return cancelled
382392

383393
def _validate_task_id_match(self, task_id: str, event_task_id: str) -> None:
@@ -657,7 +667,7 @@ async def on_subscribe_to_task( # noqa: D102
657667

658668
# Not running here: serve the snapshot and tail the remote stream.
659669
async for event in self._subscribe_remote(
660-
task_id, task, snapshot_version, stream
670+
task_id, task, snapshot_version, stream, context
661671
):
662672
yield event
663673

@@ -667,13 +677,22 @@ async def _subscribe_remote(
667677
task: Task,
668678
snapshot_version: TaskVersion,
669679
stream: TaskEventStream,
680+
context: ServerCallContext,
670681
) -> AsyncGenerator[Event, None]:
671682
"""Serves a resubscription for a task running on another replica."""
672683
yield task
673684

674-
async with aclosing(
675-
stream.subscribe(task_id, after=snapshot_version)
676-
) as subscription:
685+
if _stream_accepts_context(stream, 'subscribe'):
686+
# TODO(ISSUE #1374): remove this check once ServerCallContext is a required parameter on TaskEventStream.
687+
subscription_gen = stream.subscribe(
688+
task_id,
689+
after=snapshot_version,
690+
context=context, # ty:ignore[unknown-argument]
691+
)
692+
else:
693+
subscription_gen = stream.subscribe(task_id, after=snapshot_version)
694+
695+
async with aclosing(subscription_gen) as subscription:
677696
async for versioned in subscription:
678697
if not versioned.version.is_after(snapshot_version):
679698
continue

0 commit comments

Comments
 (0)