Skip to content

Commit 1d4dcb7

Browse files
ehsavoieehsavoie
committed
WIP Rest javadoc
Signed-off-by: Emmanuel Hugonnet <ehugonne@redhat.com>
1 parent e8fd7f2 commit 1d4dcb7

3 files changed

Lines changed: 202 additions & 0 deletions

File tree

‎transport/rest/src/main/java/io/a2a/transport/rest/handler/RestHandler.java‎

Lines changed: 181 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -65,6 +65,16 @@
6565
import mutiny.zero.ZeroPublisher;
6666
import org.jspecify.annotations.Nullable;
6767

68+
/**
69+
* REST transport handler for processing A2A protocol requests over HTTP.
70+
*
71+
* <p>This handler converts HTTP REST requests into A2A protocol operations and
72+
* manages the lifecycle of agent interactions including message sending, task
73+
* management, and push notification configurations.
74+
*
75+
* <p>The handler supports both blocking and streaming operations, and validates
76+
* protocol versions and required extensions before processing requests.
77+
*/
6878
@ApplicationScoped
6979
public class RestHandler {
7080

@@ -90,6 +100,14 @@ protected RestHandler() {
90100
this.executor = null;
91101
}
92102

103+
/**
104+
* Creates a REST handler with full CDI injection support.
105+
*
106+
* @param agentCard the public agent card containing agent capabilities
107+
* @param extendedAgentCard optional extended agent card instance
108+
* @param requestHandler the handler for processing A2A requests
109+
* @param executor the executor for asynchronous operations
110+
*/
93111
@Inject
94112
public RestHandler(@PublicAgentCard AgentCard agentCard, @ExtendedAgentCard Instance<AgentCard> extendedAgentCard,
95113
RequestHandler requestHandler, @Internal Executor executor) {
@@ -102,12 +120,27 @@ public RestHandler(@PublicAgentCard AgentCard agentCard, @ExtendedAgentCard Inst
102120
AgentCardValidator.validateTransportConfiguration(agentCard);
103121
}
104122

123+
/**
124+
* Creates a REST handler with basic dependencies.
125+
*
126+
* @param agentCard the agent card containing agent capabilities
127+
* @param requestHandler the handler for processing A2A requests
128+
* @param executor the executor for asynchronous operations
129+
*/
105130
public RestHandler(AgentCard agentCard, RequestHandler requestHandler, Executor executor) {
106131
this.agentCard = agentCard;
107132
this.requestHandler = requestHandler;
108133
this.executor = executor;
109134
}
110135

136+
/**
137+
* Handles a blocking message send request.
138+
*
139+
* @param context the server call context containing authentication and metadata
140+
* @param tenant the tenant identifier
141+
* @param body the JSON request body
142+
* @return the HTTP response containing the task or message result
143+
*/
111144
public HTTPRestResponse sendMessage(ServerCallContext context, String tenant, String body) {
112145

113146
try {
@@ -125,6 +158,14 @@ public HTTPRestResponse sendMessage(ServerCallContext context, String tenant, St
125158
}
126159
}
127160

161+
/**
162+
* Handles a streaming message send request.
163+
*
164+
* @param context the server call context containing authentication and metadata
165+
* @param tenant the tenant identifier
166+
* @param body the JSON request body
167+
* @return the streaming HTTP response containing a publisher of events
168+
*/
128169
public HTTPRestResponse sendStreamingMessage(ServerCallContext context, String tenant, String body) {
129170
try {
130171
if (!agentCard.capabilities().streaming()) {
@@ -144,6 +185,14 @@ public HTTPRestResponse sendStreamingMessage(ServerCallContext context, String t
144185
}
145186
}
146187

188+
/**
189+
* Handles a task cancellation request.
190+
*
191+
* @param context the server call context containing authentication and metadata
192+
* @param tenant the tenant identifier
193+
* @param taskId the ID of the task to cancel
194+
* @return the HTTP response containing the cancelled task
195+
*/
147196
public HTTPRestResponse cancelTask(ServerCallContext context, String tenant, String taskId) {
148197
try {
149198
if (taskId == null || taskId.isEmpty()) {
@@ -162,6 +211,15 @@ public HTTPRestResponse cancelTask(ServerCallContext context, String tenant, Str
162211
}
163212
}
164213

214+
/**
215+
* Creates a push notification configuration for a task.
216+
*
217+
* @param context the server call context containing authentication and metadata
218+
* @param tenant the tenant identifier
219+
* @param body the JSON request body containing the configuration
220+
* @param taskId the ID of the task
221+
* @return the HTTP response containing the created configuration
222+
*/
165223
public HTTPRestResponse createTaskPushNotificationConfiguration(ServerCallContext context, String tenant, String body, String taskId) {
166224
try {
167225
if (!agentCard.capabilities().pushNotifications()) {
@@ -179,6 +237,14 @@ public HTTPRestResponse createTaskPushNotificationConfiguration(ServerCallContex
179237
}
180238
}
181239

240+
/**
241+
* Subscribes to task updates via a streaming connection.
242+
*
243+
* @param context the server call context containing authentication and metadata
244+
* @param tenant the tenant identifier
245+
* @param taskId the ID of the task to subscribe to
246+
* @return the streaming HTTP response containing task updates
247+
*/
182248
public HTTPRestResponse subscribeToTask(ServerCallContext context, String tenant, String taskId) {
183249
try {
184250
if (!agentCard.capabilities().streaming()) {
@@ -194,6 +260,15 @@ public HTTPRestResponse subscribeToTask(ServerCallContext context, String tenant
194260
}
195261
}
196262

263+
/**
264+
* Retrieves a task by ID.
265+
*
266+
* @param context the server call context containing authentication and metadata
267+
* @param tenant the tenant identifier
268+
* @param taskId the ID of the task to retrieve
269+
* @param historyLength the maximum number of history entries to include
270+
* @return the HTTP response containing the task
271+
*/
197272
public HTTPRestResponse getTask(ServerCallContext context, String tenant, String taskId, @Nullable Integer historyLength) {
198273
try {
199274
TaskQueryParams params = new TaskQueryParams(taskId, historyLength, tenant);
@@ -209,6 +284,20 @@ public HTTPRestResponse getTask(ServerCallContext context, String tenant, String
209284
}
210285
}
211286

287+
/**
288+
* Lists tasks with optional filtering and pagination.
289+
*
290+
* @param context the server call context containing authentication and metadata
291+
* @param tenant the tenant identifier
292+
* @param contextId optional context ID to filter by
293+
* @param status optional task status to filter by
294+
* @param pageSize optional maximum number of tasks to return
295+
* @param pageToken optional token for pagination
296+
* @param historyLength optional maximum number of history entries per task
297+
* @param statusTimestampAfter optional ISO-8601 timestamp to filter tasks updated after
298+
* @param includeArtifacts optional flag to include task artifacts
299+
* @return the HTTP response containing the list of tasks
300+
*/
212301
public HTTPRestResponse listTasks(ServerCallContext context, String tenant,
213302
@Nullable String contextId, @Nullable String status,
214303
@Nullable Integer pageSize, @Nullable String pageToken,
@@ -271,6 +360,15 @@ public HTTPRestResponse listTasks(ServerCallContext context, String tenant,
271360
}
272361
}
273362

363+
/**
364+
* Retrieves a specific push notification configuration for a task.
365+
*
366+
* @param context the server call context containing authentication and metadata
367+
* @param tenant the tenant identifier
368+
* @param taskId the ID of the task
369+
* @param configId the ID of the configuration to retrieve
370+
* @return the HTTP response containing the configuration
371+
*/
274372
public HTTPRestResponse getTaskPushNotificationConfiguration(ServerCallContext context, String tenant, String taskId, String configId) {
275373
try {
276374
if (!agentCard.capabilities().pushNotifications()) {
@@ -286,6 +384,16 @@ public HTTPRestResponse getTaskPushNotificationConfiguration(ServerCallContext c
286384
}
287385
}
288386

387+
/**
388+
* Lists push notification configurations for a task.
389+
*
390+
* @param context the server call context containing authentication and metadata
391+
* @param tenant the tenant identifier
392+
* @param taskId the ID of the task
393+
* @param pageSize the maximum number of configurations to return
394+
* @param pageToken the token for pagination
395+
* @return the HTTP response containing the list of configurations
396+
*/
289397
public HTTPRestResponse listTaskPushNotificationConfigurations(ServerCallContext context, String tenant, String taskId, int pageSize, String pageToken) {
290398
try {
291399
if (!agentCard.capabilities().pushNotifications()) {
@@ -301,6 +409,15 @@ public HTTPRestResponse listTaskPushNotificationConfigurations(ServerCallContext
301409
}
302410
}
303411

412+
/**
413+
* Deletes a push notification configuration for a task.
414+
*
415+
* @param context the server call context containing authentication and metadata
416+
* @param tenant the tenant identifier
417+
* @param taskId the ID of the task
418+
* @param configId the ID of the configuration to delete
419+
* @return the HTTP response with no content on success
420+
*/
304421
public HTTPRestResponse deleteTaskPushNotificationConfiguration(ServerCallContext context, String tenant, String taskId, String configId) {
305422
try {
306423
if (!agentCard.capabilities().pushNotifications()) {
@@ -348,6 +465,12 @@ private HTTPRestResponse createSuccessResponse(int statusCode, com.google.protob
348465
}
349466
}
350467

468+
/**
469+
* Creates an HTTP error response from an A2A error.
470+
*
471+
* @param error the A2A error to convert
472+
* @return the HTTP response with appropriate status code and error details
473+
*/
351474
public HTTPRestResponse createErrorResponse(A2AError error) {
352475
int statusCode = mapErrorToHttpStatus(error);
353476
return createErrorResponse(statusCode, error);
@@ -459,6 +582,13 @@ private int mapErrorToHttpStatus(A2AError error) {
459582
return 500;
460583
}
461584

585+
/**
586+
* Retrieves the extended agent card if configured.
587+
*
588+
* @param context the server call context containing authentication and metadata
589+
* @param tenant the tenant identifier
590+
* @return the HTTP response containing the extended agent card
591+
*/
462592
public HTTPRestResponse getExtendedAgentCard(ServerCallContext context, String tenant) {
463593
try {
464594
if (!agentCard.capabilities().extendedAgentCard() || extendedAgentCard == null || !extendedAgentCard.isResolvable()) {
@@ -472,6 +602,11 @@ public HTTPRestResponse getExtendedAgentCard(ServerCallContext context, String t
472602
}
473603
}
474604

605+
/**
606+
* Retrieves the public agent card.
607+
*
608+
* @return the HTTP response containing the agent card
609+
*/
475610
public HTTPRestResponse getAgentCard() {
476611
try {
477612
return new HTTPRestResponse(200, "application/json", JsonUtil.toJson(agentCard));
@@ -480,26 +615,51 @@ public HTTPRestResponse getAgentCard() {
480615
}
481616
}
482617

618+
/**
619+
* Represents an HTTP REST response with status code, content type, and body.
620+
*/
483621
public static class HTTPRestResponse {
484622

485623
private final int statusCode;
486624
private final String contentType;
487625
private final String body;
488626

627+
/**
628+
* Creates an HTTP REST response.
629+
*
630+
* @param statusCode the HTTP status code
631+
* @param contentType the content type of the response
632+
* @param body the response body
633+
*/
489634
public HTTPRestResponse(int statusCode, String contentType, String body) {
490635
this.statusCode = statusCode;
491636
this.contentType = contentType;
492637
this.body = body;
493638
}
494639

640+
/**
641+
* Returns the HTTP status code.
642+
*
643+
* @return the status code
644+
*/
495645
public int getStatusCode() {
496646
return statusCode;
497647
}
498648

649+
/**
650+
* Returns the content type.
651+
*
652+
* @return the content type
653+
*/
499654
public String getContentType() {
500655
return contentType;
501656
}
502657

658+
/**
659+
* Returns the response body.
660+
*
661+
* @return the body
662+
*/
503663
public String getBody() {
504664
return body;
505665
}
@@ -510,26 +670,47 @@ public String toString() {
510670
}
511671
}
512672

673+
/**
674+
* Represents an HTTP streaming response with Server-Sent Events.
675+
*/
513676
public static class HTTPRestStreamingResponse extends HTTPRestResponse {
514677

515678
private final Flow.Publisher<String> publisher;
516679

680+
/**
681+
* Creates an HTTP streaming response.
682+
*
683+
* @param publisher the publisher of streaming events
684+
*/
517685
public HTTPRestStreamingResponse(Flow.Publisher<String> publisher) {
518686
super(200, "text/event-stream", "");
519687
this.publisher = publisher;
520688
}
521689

690+
/**
691+
* Returns the publisher for streaming events.
692+
*
693+
* @return the publisher
694+
*/
522695
public Flow.Publisher<String> getPublisher() {
523696
return publisher;
524697
}
525698
}
526699

700+
/**
701+
* Represents an HTTP error response containing A2A error details.
702+
*/
527703
private static class HTTPRestErrorResponse {
528704

529705
private final String error;
530706
private final @Nullable
531707
String message;
532708

709+
/**
710+
* Creates an error response from an A2A error.
711+
*
712+
* @param jsonRpcError the A2A error
713+
*/
533714
private HTTPRestErrorResponse(A2AError jsonRpcError) {
534715
this.error = jsonRpcError.getClass().getName();
535716
this.message = jsonRpcError.getMessage();

‎transport/rest/src/main/java/io/a2a/transport/rest/handler/package-info.java‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,15 @@
1+
/**
2+
* REST transport handler implementations for the A2A protocol.
3+
*
4+
* <p>This package contains the core REST handler that processes HTTP requests
5+
* and translates them to A2A protocol operations. It includes support for:
6+
* <ul>
7+
* <li>Message sending (blocking and streaming)</li>
8+
* <li>Task management and querying</li>
9+
* <li>Push notification configurations</li>
10+
* <li>Agent card retrieval</li>
11+
* </ul>
12+
*/
113
@NullMarked
214
package io.a2a.transport.rest.handler;
315

‎transport/rest/src/test/java/io/a2a/transport/rest/handler/RestTestTransportMetadata.java‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,16 @@
33
import io.a2a.server.TransportMetadata;
44
import io.a2a.spec.TransportProtocol;
55

6+
/**
7+
* Test implementation of TransportMetadata for REST transport testing.
8+
*/
69
public class RestTestTransportMetadata implements TransportMetadata {
10+
11+
/**
12+
* Returns the transport protocol used for REST communication.
13+
*
14+
* @return the HTTP JSON transport protocol identifier
15+
*/
716
@Override
817
public String getTransportProtocol() {
918
return TransportProtocol.HTTP_JSON.asString();

0 commit comments

Comments
 (0)