Skip to content

Commit b7cba7c

Browse files
authored
fix(server): use keyset cursors for ListTasks page tokens (#1282)
A ListTasks page token was the ID of the first task of the next page, and each store looked that task up again to decide where to resume. If the task was updated between requests, the listing restarted and returned duplicates; if it was deleted, the request failed with InvalidParamsError. The token now carries the sort position (timestamp, id) of the last task returned, and the next page starts strictly after it, so changes to that task no longer affect pagination. The database store no longer needs an extra query to resolve the token. Tokens issued by earlier versions are still accepted and resolved the old way. Fixes #1280
1 parent 5ca9859 commit b7cba7c

7 files changed

Lines changed: 509 additions & 78 deletions

File tree

‎.github/actions/spelling/allow.txt‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -167,6 +167,7 @@ TResponse
167167
typ
168168
typeerror
169169
UIDs
170+
urlsafe
170171
versioned
171172
Versioned
172173
vulnz

‎src/a2a/server/tasks/database_task_store.py‎

Lines changed: 104 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
import logging
22

33
from collections.abc import Callable
4+
from datetime import datetime
45
from typing import Any, cast
56

67

@@ -22,6 +23,7 @@
2223
"or 'pip install a2a-sdk[sql]'"
2324
) from e
2425
from google.protobuf.json_format import MessageToDict, ParseDict
26+
from google.protobuf.timestamp_pb2 import Timestamp
2527

2628
from a2a.compat.v0_3.model_conversions import (
2729
compat_task_model_to_core,
@@ -34,12 +36,31 @@
3436
from a2a.types.a2a_pb2 import Task
3537
from a2a.utils.constants import DEFAULT_LIST_TASKS_PAGE_SIZE
3638
from a2a.utils.errors import InvalidParamsError
37-
from a2a.utils.task import decode_page_token, encode_page_token
39+
from a2a.utils.task import (
40+
ListTasksCursor,
41+
decode_list_tasks_cursor,
42+
decode_page_token,
43+
encode_list_tasks_cursor,
44+
)
3845

3946

4047
logger = logging.getLogger(__name__)
4148

4249

50+
def _datetime_to_ns(value: datetime) -> int:
51+
"""Nanoseconds since the epoch for a stored (naive UTC) `last_updated`."""
52+
timestamp = Timestamp()
53+
timestamp.FromDatetime(value)
54+
return timestamp.ToNanoseconds()
55+
56+
57+
def _ns_to_datetime(timestamp_ns: int) -> datetime:
58+
"""Inverse of `_datetime_to_ns`, as a naive UTC datetime."""
59+
timestamp = Timestamp()
60+
timestamp.FromNanoseconds(timestamp_ns)
61+
return timestamp.ToDatetime()
62+
63+
4364
class DatabaseTaskStore(TaskStore):
4465
"""SQLAlchemy-based implementation of TaskStore.
4566
@@ -257,64 +278,109 @@ async def list(
257278
self.task_model.id.desc(),
258279
)
259280

260-
# Get paginated results
281+
# Get paginated results. The page token carries the position of the
282+
# last task returned, so it stays valid if that task is updated or
283+
# deleted. A task updated mid-listing can move above the cursor and
284+
# be skipped.
261285
if params.page_token:
262-
start_task_id = decode_page_token(params.page_token)
263-
start_task = (
264-
await session.execute(
265-
select(self.task_model).where(
266-
and_(
267-
self.task_model.id == start_task_id,
268-
self.task_model.owner == owner,
269-
)
286+
cursor = decode_list_tasks_cursor(params.page_token)
287+
if cursor is None:
288+
stmt = stmt.where(
289+
await self._legacy_page_clause(
290+
session, owner, params.page_token
270291
)
271292
)
272-
).scalar_one_or_none()
273-
if not start_task:
274-
raise InvalidParamsError(
275-
f'Invalid page token: {params.page_token}'
276-
)
277-
278-
start_task_timestamp = start_task.last_updated
279-
where_clauses = []
280-
if start_task_timestamp:
281-
where_clauses.append(
282-
and_(
283-
timestamp_col == start_task_timestamp,
284-
self.task_model.id <= start_task_id,
285-
)
286-
)
287-
where_clauses.append(timestamp_col < start_task_timestamp)
288-
where_clauses.append(timestamp_col.is_(None))
289293
else:
290-
where_clauses.append(
291-
and_(
292-
timestamp_col.is_(None),
293-
self.task_model.id <= start_task_id,
294-
)
295-
)
296-
stmt = stmt.where(or_(*where_clauses))
294+
stmt = stmt.where(self._after_cursor(cursor))
297295

298296
page_size = params.page_size or DEFAULT_LIST_TASKS_PAGE_SIZE
299297
stmt = stmt.limit(page_size + 1) # Add 1 for next page token
300298

301299
result = await session.execute(stmt)
302300
tasks_models = result.scalars().all()
303-
tasks = [self._from_orm(task_model) for task_model in tasks_models]
301+
page_models = tasks_models[:page_size]
304302

305303
next_page_token = (
306-
encode_page_token(tasks[-1].id)
307-
if len(tasks) == page_size + 1
304+
encode_list_tasks_cursor(self._cursor_for(page_models[-1]))
305+
if len(tasks_models) == page_size + 1
308306
else None
309307
)
310308

311309
return a2a_pb2.ListTasksResponse(
312-
tasks=tasks[:page_size],
310+
tasks=[
311+
self._from_orm(task_model) for task_model in page_models
312+
],
313313
total_size=total_count,
314314
next_page_token=next_page_token,
315315
page_size=page_size,
316316
)
317317

318+
@staticmethod
319+
def _cursor_for(task_model: TaskModel) -> ListTasksCursor:
320+
# From the stored column, not the proto, so the cursor compares equal
321+
# at the database's own timestamp precision.
322+
last_updated = task_model.last_updated
323+
return ListTasksCursor(
324+
timestamp_ns=_datetime_to_ns(last_updated)
325+
if last_updated is not None
326+
else None,
327+
task_id=task_model.id,
328+
)
329+
330+
def _after_cursor(self, cursor: ListTasksCursor) -> Any:
331+
"""Rows strictly after `cursor` in the `ListTasks` sort order."""
332+
timestamp_col = self.task_model.last_updated
333+
if cursor.timestamp_ns is None:
334+
return and_(
335+
timestamp_col.is_(None), self.task_model.id < cursor.task_id
336+
)
337+
try:
338+
cursor_timestamp = _ns_to_datetime(cursor.timestamp_ns)
339+
except OverflowError as e:
340+
raise InvalidParamsError('Invalid page token') from e
341+
return or_(
342+
timestamp_col < cursor_timestamp,
343+
and_(
344+
timestamp_col == cursor_timestamp,
345+
self.task_model.id < cursor.task_id,
346+
),
347+
timestamp_col.is_(None),
348+
)
349+
350+
async def _legacy_page_clause(
351+
self, session: AsyncSession, owner: str, page_token: str
352+
) -> Any:
353+
"""Resolves a legacy page token, which names the first task of the page."""
354+
timestamp_col = self.task_model.last_updated
355+
start_task_id = decode_page_token(page_token)
356+
start_task = (
357+
await session.execute(
358+
select(self.task_model).where(
359+
and_(
360+
self.task_model.id == start_task_id,
361+
self.task_model.owner == owner,
362+
)
363+
)
364+
)
365+
).scalar_one_or_none()
366+
if not start_task:
367+
raise InvalidParamsError(f'Invalid page token: {page_token}')
368+
369+
start_task_timestamp = start_task.last_updated
370+
if start_task_timestamp:
371+
return or_(
372+
and_(
373+
timestamp_col == start_task_timestamp,
374+
self.task_model.id <= start_task_id,
375+
),
376+
timestamp_col < start_task_timestamp,
377+
timestamp_col.is_(None),
378+
)
379+
return and_(
380+
timestamp_col.is_(None),
381+
self.task_model.id <= start_task_id,
382+
)
383+
318384
async def delete(self, task_id: str, context: ServerCallContext) -> None:
319385
"""Deletes a task from the database by ID, for the given owner."""
320386
await self._ensure_initialized()

‎src/a2a/server/tasks/inmemory_task_store.py‎

Lines changed: 53 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,8 @@
11
import logging
22
import threading
33

4+
from collections.abc import Sequence
5+
46
from a2a.server.context import ServerCallContext
57
from a2a.server.owner_resolver import OwnerResolver, resolve_user_scope
68
from a2a.server.tasks.copying_task_store import CopyingTaskStoreAdapter
@@ -9,12 +11,36 @@
911
from a2a.types.a2a_pb2 import Task
1012
from a2a.utils.constants import DEFAULT_LIST_TASKS_PAGE_SIZE
1113
from a2a.utils.errors import InvalidParamsError
12-
from a2a.utils.task import decode_page_token, encode_page_token
14+
from a2a.utils.task import (
15+
ListTasksCursor,
16+
decode_list_tasks_cursor,
17+
decode_page_token,
18+
encode_list_tasks_cursor,
19+
)
1320

1421

1522
logger = logging.getLogger(__name__)
1623

1724

25+
def _list_sort_key(task: Task) -> tuple[bool, int, str]:
26+
"""`ListTasks` sort key: `(has timestamp, timestamp, id)`, sorted descending."""
27+
has_timestamp = task.HasField('status') and task.status.HasField(
28+
'timestamp'
29+
)
30+
return (
31+
has_timestamp,
32+
task.status.timestamp.ToNanoseconds() if has_timestamp else 0,
33+
task.id,
34+
)
35+
36+
37+
def _cursor_for(task: Task) -> ListTasksCursor:
38+
has_timestamp, timestamp_ns, task_id = _list_sort_key(task)
39+
return ListTasksCursor(
40+
timestamp_ns=timestamp_ns if has_timestamp else None, task_id=task_id
41+
)
42+
43+
1844
class _InMemoryTaskStoreImpl(TaskStore):
1945
"""Internal In-memory implementation of TaskStore.
2046
@@ -108,38 +134,31 @@ async def list(
108134
]
109135

110136
# Order tasks by last update time. To ensure stable sorting, in cases where timestamps are null or not unique, do a second order comparison of IDs.
111-
tasks.sort(
112-
key=lambda task: (
113-
task.status.HasField('timestamp')
114-
if task.HasField('status')
115-
else False,
116-
task.status.timestamp.ToNanoseconds()
117-
if task.HasField('status') and task.status.HasField('timestamp')
118-
else 0,
119-
task.id,
120-
),
121-
reverse=True,
122-
)
137+
tasks.sort(key=_list_sort_key, reverse=True)
123138

124-
# Paginate tasks
139+
# Paginate tasks. The page token carries the position of the last task
140+
# returned, so it stays valid if that task is updated or deleted. A
141+
# task updated mid-listing can move above the cursor and be skipped.
125142
total_size = len(tasks)
126143
start_idx = 0
127144
if params.page_token:
128-
start_task_id = decode_page_token(params.page_token)
129-
valid_token = False
130-
for i, task in enumerate(tasks):
131-
if task.id == start_task_id:
132-
start_idx = i
133-
valid_token = True
134-
break
135-
if not valid_token:
136-
raise InvalidParamsError(
137-
f'Invalid page token: {params.page_token}'
145+
cursor = decode_list_tasks_cursor(params.page_token)
146+
if cursor is None:
147+
start_idx = self._legacy_start_index(tasks, params.page_token)
148+
else:
149+
after = cursor.sort_key()
150+
start_idx = next(
151+
(
152+
i
153+
for i, task in enumerate(tasks)
154+
if _list_sort_key(task) < after
155+
),
156+
total_size,
138157
)
139158
page_size = params.page_size or DEFAULT_LIST_TASKS_PAGE_SIZE
140159
end_idx = start_idx + page_size
141160
next_page_token = (
142-
encode_page_token(tasks[end_idx].id)
161+
encode_list_tasks_cursor(_cursor_for(tasks[end_idx - 1]))
143162
if end_idx < total_size
144163
else None
145164
)
@@ -152,6 +171,15 @@ async def list(
152171
page_size=page_size,
153172
)
154173

174+
@staticmethod
175+
def _legacy_start_index(tasks: Sequence[Task], page_token: str) -> int:
176+
"""Resolves a legacy page token, which names the first task of the page."""
177+
start_task_id = decode_page_token(page_token)
178+
for i, task in enumerate(tasks):
179+
if task.id == start_task_id:
180+
return i
181+
raise InvalidParamsError(f'Invalid page token: {page_token}')
182+
155183
async def delete(self, task_id: str, context: ServerCallContext) -> None:
156184
"""Deletes a task from the in-memory store by ID, for the given owner."""
157185
owner = self.owner_resolver(context)

0 commit comments

Comments
 (0)