Skip to content

Commit ae3e01b

Browse files
kabirehsavoie
andauthored
chore: Centralise PageToken parsing (#601)
fixes: #597 --------- Signed-off-by: Emmanuel Hugonnet <ehugonne@redhat.com> Co-authored-by: Emmanuel Hugonnet <ehugonne@redhat.com>
1 parent d3e5b28 commit ae3e01b

6 files changed

Lines changed: 285 additions & 100 deletions

File tree

‎extras/push-notification-config-store-database-jpa/src/main/java/io/a2a/extras/pushnotificationconfigstore/database/jpa/JpaDatabasePushNotificationConfigStore.java‎

Lines changed: 10 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,7 @@
1515
import io.a2a.server.tasks.PushNotificationConfigStore;
1616
import io.a2a.spec.ListTaskPushNotificationConfigParams;
1717
import io.a2a.spec.ListTaskPushNotificationConfigResult;
18+
import io.a2a.util.PageToken;
1819
import io.a2a.spec.PushNotificationConfig;
1920
import io.a2a.spec.TaskPushNotificationConfig;
2021
import java.util.stream.Collectors;
@@ -79,18 +80,17 @@ public ListTaskPushNotificationConfigResult getInfo(ListTaskPushNotificationConf
7980
String taskId = params.id();
8081
LOGGER.debug("Retrieving PushNotificationConfigs for Task '{}' with params: pageSize={}, pageToken={}",
8182
taskId, params.pageSize(), params.pageToken());
83+
84+
// Parse pageToken once at the beginning
85+
PageToken pageToken = PageToken.fromString(params.pageToken());
86+
8287
try {
8388
StringBuilder queryBuilder = new StringBuilder("SELECT c FROM JpaPushNotificationConfig c WHERE c.id.taskId = :taskId");
8489

85-
if (params.pageToken() != null && !params.pageToken().isEmpty()) {
86-
String[] tokenParts = params.pageToken().split(":", 2);
87-
if (tokenParts.length == 2) {
90+
if (pageToken != null) {
8891
// Keyset pagination: get tasks where timestamp < tokenTimestamp OR (timestamp = tokenTimestamp AND id > tokenId)
8992
// All tasks have timestamps (TaskStatus canonical constructor ensures this)
9093
queryBuilder.append(" AND (COALESCE(c.createdAt, :nullSentinel) < :tokenTimestamp OR (COALESCE(c.createdAt, :nullSentinel) = :tokenTimestamp AND c.id.configId > :tokenId))");
91-
} else {
92-
// Based on the comments in the test case, if the pageToken is invalid start from the beginning.
93-
}
9494
}
9595

9696
queryBuilder.append(" ORDER BY COALESCE(c.createdAt, :nullSentinel) DESC, c.id.configId ASC");
@@ -99,22 +99,9 @@ public ListTaskPushNotificationConfigResult getInfo(ListTaskPushNotificationConf
9999
query.setParameter("taskId", taskId);
100100
query.setParameter("nullSentinel", NULL_TIMESTAMP_SENTINEL);
101101

102-
if (params.pageToken() != null && !params.pageToken().isEmpty()) {
103-
String[] tokenParts = params.pageToken().split(":", 2);
104-
if (tokenParts.length == 2) {
105-
try {
106-
long timestampMillis = Long.parseLong(tokenParts[0]);
107-
String tokenId = tokenParts[1];
108-
109-
Instant tokenTimestamp = Instant.ofEpochMilli(timestampMillis);
110-
query.setParameter("tokenTimestamp", tokenTimestamp);
111-
query.setParameter("tokenId", tokenId);
112-
} catch (NumberFormatException e) {
113-
// Malformed timestamp in pageToken
114-
throw new io.a2a.spec.InvalidParamsError(null,
115-
"Invalid pageToken format: timestamp must be numeric milliseconds", null);
116-
}
117-
}
102+
if (pageToken != null) {
103+
query.setParameter("tokenTimestamp", pageToken.timestamp());
104+
query.setParameter("tokenId", pageToken.id());
118105
}
119106

120107
int pageSize = params.getEffectivePageSize();
@@ -128,7 +115,7 @@ public ListTaskPushNotificationConfigResult getInfo(ListTaskPushNotificationConf
128115
jpaConfigsPage = jpaConfigsPage.subList(0, pageSize);
129116
JpaPushNotificationConfig lastConfig = jpaConfigsPage.get(jpaConfigsPage.size() - 1);
130117
Instant timestamp = lastConfig.getCreatedAt() != null ? lastConfig.getCreatedAt() : NULL_TIMESTAMP_SENTINEL;
131-
nextPageToken = timestamp.toEpochMilli() + ":" + lastConfig.getId().getConfigId();
118+
nextPageToken = new PageToken(timestamp, lastConfig.getId().getConfigId()).toString();
132119
}
133120

134121
List<PushNotificationConfig> configs = jpaConfigsPage.stream()

‎extras/push-notification-config-store-database-jpa/src/test/java/io/a2a/extras/pushnotificationconfigstore/database/jpa/JpaDatabasePushNotificationConfigStoreIntegrationTest.java‎

Lines changed: 5 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -352,15 +352,12 @@ public void testPaginationWithInvalidToken() {
352352
// Create 5 configs
353353
createSamples(taskId, 5);
354354

355-
// Request with invalid pageToken - JPA implementation behavior is to start from beginning
355+
// Request with invalid pageToken - should throw InvalidParamsError for invalid format
356356
ListTaskPushNotificationConfigParams params = new ListTaskPushNotificationConfigParams(
357357
taskId, 2, "invalid_token_that_does_not_exist", "");
358-
ListTaskPushNotificationConfigResult result = pushNotificationConfigStore.getInfo(params);
359358

360-
assertNotNull(result);
361-
// When token is not found, implementation starts from beginning
362-
assertEquals(2, result.configs().size(), "Should return first page when token is not found");
363-
assertNotNull(result.nextPageToken(), "Should have nextPageToken since more items exist");
359+
assertThrows(io.a2a.spec.InvalidParamsError.class, () -> pushNotificationConfigStore.getInfo(params),
360+
"Should throw InvalidParamsError for invalid pageToken format (missing colon)");
364361
}
365362

366363
@Test
@@ -428,12 +425,9 @@ public void testPageTokenWithMissingColon() {
428425

429426
ListTaskPushNotificationConfigParams params =
430427
new ListTaskPushNotificationConfigParams(taskId, 2, "123456789cfg1", "");
431-
ListTaskPushNotificationConfigResult result = pushNotificationConfigStore.getInfo(params);
432428

433-
assertNotNull(result);
434-
assertEquals(2, result.configs().size(),
435-
"Should return first page when pageToken format is invalid (missing colon)");
436-
assertNotNull(result.nextPageToken(), "Should have nextPageToken since more items exist");
429+
assertThrows(io.a2a.spec.InvalidParamsError.class, () -> pushNotificationConfigStore.getInfo(params),
430+
"Should throw InvalidParamsError for invalid pageToken format (missing colon)");
437431
}
438432

439433
@Test

‎extras/task-store-database-jpa/src/main/java/io/a2a/extras/taskstore/database/jpa/JpaDatabaseTaskStore.java‎

Lines changed: 6 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,7 @@
2525
import io.a2a.spec.Artifact;
2626
import io.a2a.spec.ListTasksParams;
2727
import io.a2a.spec.Message;
28+
import io.a2a.util.PageToken;
2829
import io.a2a.spec.Task;
2930
import org.slf4j.Logger;
3031
import org.slf4j.LoggerFactory;
@@ -227,23 +228,9 @@ public ListTasksResult list(ListTasksParams params) {
227228
params.contextId(), params.status(), params.pageSize(), params.pageToken());
228229

229230
// Parse pageToken once at the beginning
230-
Instant tokenTimestamp = null;
231-
String tokenId = null;
232-
if (params.pageToken() != null && !params.pageToken().isEmpty()) {
233-
String[] tokenParts = params.pageToken().split(":", 2);
234-
if (tokenParts.length == 2) {
235-
try {
236-
long timestampMillis = Long.parseLong(tokenParts[0]);
237-
tokenId = tokenParts[1];
238-
tokenTimestamp = Instant.ofEpochMilli(timestampMillis);
239-
} catch (NumberFormatException e) {
240-
throw new io.a2a.spec.InvalidParamsError(null,
241-
"Invalid pageToken format: timestamp must be numeric milliseconds", null);
242-
}
243-
} else {
244-
throw new io.a2a.spec.InvalidParamsError(null, "Invalid pageToken format: expected 'timestamp:id'", null);
245-
}
246-
}
231+
PageToken pageToken = PageToken.fromString(params.pageToken());
232+
Instant tokenTimestamp = pageToken != null ? pageToken.timestamp() : null;
233+
String tokenId = pageToken != null ? pageToken.id() : null;
247234

248235
// Build dynamic JPQL query with WHERE clauses for filtering
249236
StringBuilder queryBuilder = new StringBuilder("SELECT t FROM JpaTask t WHERE 1=1");
@@ -337,8 +324,8 @@ public ListTasksResult list(ListTasksParams params) {
337324
if (hasMore && !tasks.isEmpty()) {
338325
Task lastTask = tasks.get(tasks.size() - 1);
339326
// All tasks have timestamps (TaskStatus canonical constructor ensures this)
340-
long timestampMillis = lastTask.status().timestamp().toInstant().toEpochMilli();
341-
nextPageToken = timestampMillis + ":" + lastTask.id();
327+
Instant timestamp = lastTask.status().timestamp().toInstant();
328+
nextPageToken = new PageToken(timestamp, lastTask.id()).toString();
342329
}
343330

344331
// Apply post-processing transformations (history limiting, artifact removal)

‎server-common/src/main/java/io/a2a/server/tasks/InMemoryTaskStore.java‎

Lines changed: 35 additions & 47 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@
1111
import io.a2a.spec.Artifact;
1212
import io.a2a.spec.ListTasksParams;
1313
import io.a2a.spec.Message;
14+
import io.a2a.util.PageToken;
1415
import io.a2a.spec.Task;
1516
import org.jspecify.annotations.Nullable;
1617

@@ -73,54 +74,41 @@ public ListTasksResult list(ListTasksParams params) {
7374

7475
// Handle page token using keyset pagination (format: "timestamp_millis:taskId")
7576
// Use binary search to efficiently find the first task after the pageToken position (O(log N))
76-
if (params.pageToken() != null && !params.pageToken().isEmpty()) {
77-
String[] tokenParts = params.pageToken().split(":", 2);
78-
if (tokenParts.length == 2) {
79-
try {
80-
long tokenTimestampMillis = Long.parseLong(tokenParts[0]);
81-
java.time.Instant tokenTimestamp = java.time.Instant.ofEpochMilli(tokenTimestampMillis);
82-
String tokenId = tokenParts[1];
83-
84-
// Binary search for first task where: timestamp < tokenTimestamp OR (timestamp == tokenTimestamp AND id > tokenId)
85-
// Since list is sorted (timestamp DESC, id ASC), we search for the insertion point
86-
int left = 0;
87-
int right = allFilteredTasks.size();
88-
89-
while (left < right) {
90-
int mid = left + (right - left) / 2;
91-
Task task = allFilteredTasks.get(mid);
92-
93-
java.time.Instant taskTimestamp = (task.status() != null && task.status().timestamp() != null)
94-
? task.status().timestamp().toInstant().truncatedTo(java.time.temporal.ChronoUnit.MILLIS)
95-
: null;
96-
97-
if (taskTimestamp == null) {
98-
// Task with null timestamp is always "before" a token with a timestamp, as they are sorted last.
99-
// So, we search in the right half.
100-
left = mid + 1;
101-
} else {
102-
int timestampCompare = taskTimestamp.compareTo(tokenTimestamp);
103-
104-
if (timestampCompare < 0 || (timestampCompare == 0 && task.id().compareTo(tokenId) > 0)) {
105-
// This task is after the token, search left half
106-
right = mid;
107-
} else {
108-
// This task is before or equal to token, search right half
109-
left = mid + 1;
110-
}
111-
}
77+
PageToken pageToken = PageToken.fromString(params.pageToken());
78+
if (pageToken != null) {
79+
java.time.Instant tokenTimestamp = pageToken.timestamp();
80+
String tokenId = pageToken.id();
81+
82+
// Binary search for first task where: timestamp < tokenTimestamp OR (timestamp == tokenTimestamp AND id > tokenId)
83+
// Since list is sorted (timestamp DESC, id ASC), we search for the insertion point
84+
int left = 0;
85+
int right = allFilteredTasks.size();
86+
87+
while (left < right) {
88+
int mid = left + (right - left) / 2;
89+
Task task = allFilteredTasks.get(mid);
90+
91+
java.time.Instant taskTimestamp = (task.status() != null && task.status().timestamp() != null)
92+
? task.status().timestamp().toInstant().truncatedTo(java.time.temporal.ChronoUnit.MILLIS)
93+
: null;
94+
95+
if (taskTimestamp == null) {
96+
// Task with null timestamp is always "before" a token with a timestamp, as they are sorted last.
97+
// So, we search in the right half.
98+
left = mid + 1;
99+
} else {
100+
int timestampCompare = taskTimestamp.compareTo(tokenTimestamp);
101+
102+
if (timestampCompare < 0 || (timestampCompare == 0 && task.id().compareTo(tokenId) > 0)) {
103+
// This task is after the token, search left half
104+
right = mid;
105+
} else {
106+
// This task is before or equal to token, search right half
107+
left = mid + 1;
112108
}
113-
startIndex = left;
114-
} catch (NumberFormatException e) {
115-
// Malformed timestamp in pageToken
116-
throw new io.a2a.spec.InvalidParamsError(null,
117-
"Invalid pageToken format: timestamp must be numeric milliseconds", null);
118109
}
119-
} else {
120-
// Legacy ID-only pageToken format is not supported with timestamp-based sorting
121-
// Throw error to prevent incorrect pagination results
122-
throw new io.a2a.spec.InvalidParamsError(null, "Invalid pageToken format: expected 'timestamp:id'", null);
123110
}
111+
startIndex = left;
124112
}
125113

126114
// Get the page of tasks
@@ -132,8 +120,8 @@ public ListTasksResult list(ListTasksParams params) {
132120
if (endIndex < allFilteredTasks.size()) {
133121
Task lastTask = allFilteredTasks.get(endIndex - 1);
134122
// All tasks have timestamps (TaskStatus canonical constructor ensures this)
135-
long timestampMillis = lastTask.status().timestamp().toInstant().toEpochMilli();
136-
nextPageToken = timestampMillis + ":" + lastTask.id();
123+
java.time.Instant timestamp = lastTask.status().timestamp().toInstant();
124+
nextPageToken = new PageToken(timestamp, lastTask.id()).toString();
137125
}
138126

139127
// Transform tasks: limit history and optionally remove artifacts
Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
package io.a2a.util;
2+
3+
import java.time.Instant;
4+
5+
import io.a2a.spec.InvalidParamsError;
6+
import org.jspecify.annotations.Nullable;
7+
8+
/**
9+
* Represents a pagination token for keyset-based pagination.
10+
* <p>
11+
* PageTokens use the format {@code "timestamp_millis:id"} where:
12+
* <ul>
13+
* <li>{@code timestamp_millis} - Unix timestamp in milliseconds (numeric)</li>
14+
* <li>{@code id} - The entity identifier (String)</li>
15+
* </ul>
16+
* This format enables efficient keyset pagination by allowing queries to resume
17+
* at a specific point in a timestamp-sorted, ID-secondary-sorted result set.
18+
*
19+
* @param timestamp The timestamp component of the page token
20+
* @param id The identifier component of the page token
21+
*/
22+
public record PageToken(Instant timestamp, String id) {
23+
24+
/**
25+
* Parses a pageToken string into a PageToken record.
26+
* <p>
27+
* Expected format: {@code "timestamp_millis:id"}
28+
*
29+
* @param tokenStr The pageToken string to parse, may be null or empty
30+
* @return A PageToken instance, or null if tokenStr is null or empty
31+
* @throws InvalidParamsError if the token format is invalid or timestamp is not numeric
32+
*/
33+
public static @Nullable PageToken fromString(@Nullable String tokenStr) {
34+
if (tokenStr == null || tokenStr.isEmpty()) {
35+
return null;
36+
}
37+
38+
String[] tokenParts = tokenStr.split(":", 2);
39+
if (tokenParts.length != 2) {
40+
throw new InvalidParamsError(null,
41+
"Invalid pageToken format: expected 'timestamp:id'", null);
42+
}
43+
44+
try {
45+
long timestampMillis = Long.parseLong(tokenParts[0]);
46+
String id = tokenParts[1];
47+
if (id.isEmpty()) {
48+
throw new InvalidParamsError(null, "Invalid pageToken format: id part cannot be empty", null);
49+
}
50+
return new PageToken(Instant.ofEpochMilli(timestampMillis), id);
51+
} catch (NumberFormatException e) {
52+
throw new InvalidParamsError(null,
53+
"Invalid pageToken format: timestamp must be numeric milliseconds", null);
54+
}
55+
}
56+
57+
/**
58+
* Converts this PageToken to its string representation.
59+
* <p>
60+
* Format: {@code "timestamp_millis:id"}
61+
*
62+
* @return The pageToken string
63+
*/
64+
@Override
65+
public String toString() {
66+
return timestamp.toEpochMilli() + ":" + id;
67+
}
68+
}

0 commit comments

Comments
 (0)