feat: refactor rest express server

Author: tchapacan

.github/workflows/run-tck.yaml

@@ -13,8 +13,12 @@ env:
   TCK_VERSION: 0.3.0.beta3
   # Tells uv to not need a venv, and instead use system
   UV_SYSTEM_PYTHON: 1
-  # SUT_JSONRPC_URL to use for the TCK and the server agent
-  SUT_JSONRPC_URL: http://localhost:41241
+  # Base URL for the SUT agent
+  SUT_BASE_URL: http://localhost:41241
+  # SUT_JSONRPC_URL to use for the TCK (JSON-RPC transport)
+  SUT_JSONRPC_URL: http://localhost:41241/a2a/jsonrpc
+  # SUT_REST_URL to use for the TCK (HTTP+REST transport)
+  SUT_REST_URL: http://localhost:41241/a2a/api
   # Slow system on CI
   TCK_STREAMING_TIMEOUT: 5.0
 
@@ -58,7 +62,7 @@ jobs:
           npm run tck:sut-agent &
       - name: Wait for SUT to start
         run: |
-          URL="${{ env.SUT_JSONRPC_URL }}/.well-known/agent-card.json"
+          URL="${{ env.SUT_BASE_URL }}/.well-known/agent-card.json"
           EXPECTED_STATUS=200
           TIMEOUT=120
           RETRY_INTERVAL=2
@@ -90,11 +94,17 @@ jobs:
             sleep "$RETRY_INTERVAL"
           done
           
-      - name: Run TCK
-        id: run-tck
+      - name: Run TCK (JSON-RPC Transport)
+        id: run-tck-jsonrpc
         timeout-minutes: 5
         run: |
-          ./run_tck.py --sut-url ${{ env.SUT_JSONRPC_URL }} --category mandatory
+          ./run_tck.py --sut-url ${{ env.SUT_JSONRPC_URL }} --category mandatory --transports jsonrpc --transport-strategy prefer_jsonrpc
+        working-directory: tck/a2a-tck
+      - name: Run TCK (HTTP+REST Transport)
+        id: run-tck-rest
+        timeout-minutes: 5
+        run: |
+          ./run_tck.py --sut-url ${{ env.SUT_REST_URL }} --category mandatory --transports rest --transport-strategy prefer_rest
         working-directory: tck/a2a-tck
       - name: Stop SUT
         if: always()

src/server/express/index.ts

@@ -3,10 +3,17 @@
  * This module provides Express.js specific functionality.
  */
 
+// Legacy A2AExpressApp class (for backward compatibility)
 export { A2AExpressApp } from "./a2a_express_app.js";
+
 export { jsonRpcHandler, jsonErrorHandler } from "./json_rpc_handler.js";
 export type { JsonRpcHandlerOptions } from "./json_rpc_handler.js";
+
 export { agentCardHandler } from "./agent_card_handler.js";
 export type { AgentCardHandlerOptions, AgentCardProvider } from "./agent_card_handler.js";
+
 export { httpRestHandler } from "./http_rest_routes.js";
 export type { HttpRestHandlerOptions } from "./http_rest_routes.js";
+
+// Deprecated exports (for backward compatibility)
+export { createHttpRestRouter } from "./http_rest_routes.js";

tck/agent/index.ts

@@ -15,7 +15,7 @@ import {
   ExecutionEventBus,
   DefaultRequestHandler
 } from "../../src/server/index.js";
-import { A2AExpressApp, jsonRpcHandler, agentCardHandler, httpRestHandler } from "../../src/server/express/index.js";
+import { jsonRpcHandler, agentCardHandler, httpRestHandler } from "../../src/server/express/index.js";
 
 /**
  * SUTAgentExecutor implements the agent's core logic.
@@ -157,8 +157,8 @@ class SUTAgentExecutor implements AgentExecutor {
 const SUTAgentCard: AgentCard = {
   name: 'SUT Agent',
   description: 'A sample agent to be used as SUT against tck tests.',
-  // Adjust the base URL and port as needed. /a2a is the default base in A2AExpressApp
-  url: 'http://localhost:41241/',
+  // Main URL points to JSON-RPC endpoint (preferred transport)
+  url: 'http://localhost:41241/a2a/jsonrpc',
   provider: {
     organization: 'A2A Samples',
     url: 'https://example.com/a2a-samples' // Added provider URL
@@ -185,9 +185,9 @@ const SUTAgentCard: AgentCard = {
   ],
   supportsAuthenticatedExtendedCard: false,
   preferredTransport: 'JSONRPC',
+  // Additional interface for HTTP+REST transport
   additionalInterfaces: [
-    {url: 'http://localhost:41241', transport: 'JSONRPC'},
-    {url: 'http://localhost:41241/v1', transport: 'HTTP+JSON'}
+    {url: 'http://localhost:41241/a2a/api', transport: 'HTTP+JSON'}
   ],
 };
 
@@ -207,15 +207,15 @@ async function main() {
 
   // 4. Setup Express app with modular handlers
   const expressApp = express();
-  
-  // Register agent card handler
+
+  // Register agent card handler at well-known location (shared by all transports)
   expressApp.use('/.well-known/agent-card.json', agentCardHandler({ agentCardProvider: requestHandler }));
 
-  // Register JSON-RPC handler at root
-  expressApp.use('/', jsonRpcHandler({ requestHandler }));
+  // Register JSON-RPC handler (preferred transport, backward compatible)
+  expressApp.use('/a2a/jsonrpc', jsonRpcHandler({ requestHandler }));
 
-  // Register HTTP+REST handler at /v1
-  expressApp.use('/v1', httpRestHandler({ requestHandler }));
+  // Register HTTP+REST handler (new feature - additional transport)
+  expressApp.use('/a2a/api', httpRestHandler({ requestHandler }));
 
   // 5. Start the server
   const PORT = process.env.PORT || 41241;
@@ -225,8 +225,6 @@ async function main() {
     }
     console.log(`[SUTAgent] Server using new framework started on http://localhost:${PORT}`);
     console.log(`[SUTAgent] Agent Card: http://localhost:${PORT}/.well-known/agent-card.json`);
-    console.log(`[SUTAgent] JSON-RPC endpoint: http://localhost:${PORT}/`);
-    console.log(`[SUTAgent] HTTP+REST endpoint: http://localhost:${PORT}/v1`);
     console.log('[SUTAgent] Press Ctrl+C to stop the server');
   });
 }

test/server/http_rest_handler.spec.ts

@@ -9,6 +9,18 @@ import { A2ARequestHandler } from '../../src/server/request_handler/a2a_request_
 import { AgentCard, Task, Message } from '../../src/types.js';
 import { A2AError } from '../../src/server/error.js';
 
+/**
+ * Test suite for httpRestHandler - HTTP+REST transport implementation
+ * 
+ * This suite tests the REST API endpoints following the A2A specification:
+ * - GET /v1/card - Agent card retrieval
+ * - POST /v1/message:send - Send message (non-streaming)
+ * - POST /v1/message:stream - Send message with SSE streaming
+ * - GET /v1/tasks/:taskId - Get task status
+ * - POST /v1/tasks/:taskId:cancel - Cancel task
+ * - POST /v1/tasks/:taskId:subscribe - Resubscribe to task updates
+ * - Push notification config CRUD operations
+ */
 describe('httpRestHandler', () => {
     let mockRequestHandler: A2ARequestHandler;
     let app: Express;
@@ -312,26 +324,26 @@ describe('httpRestHandler', () => {
                 assert.deepEqual(response.body, mockConfig);
             });
 
-        it('should return 501 if push notifications not supported', async () => {
-            // Create new app with handler that has capabilities without push notifications
-            const noPNRequestHandler = {
-                ...mockRequestHandler,
-                getAgentCard: sinon.stub().resolves({ 
-                    ...testAgentCard, 
-                    capabilities: { streaming: false, pushNotifications: false } 
-                })
-            };
-            const noPNApp = express();
-            noPNApp.use(httpRestHandler({ requestHandler: noPNRequestHandler as any }));
-
-            const response = await request(noPNApp)
-                .post('/v1/tasks/task-1/pushNotificationConfigs')
-                .send({ url: 'https://example.com/webhook', events: ['message'] })
-                .expect(501);
+            it('should return 501 if push notifications not supported', async () => {
+                // Create new app with handler that has capabilities without push notifications
+                const noPNRequestHandler = {
+                    ...mockRequestHandler,
+                    getAgentCard: sinon.stub().resolves({ 
+                        ...testAgentCard, 
+                        capabilities: { streaming: false, pushNotifications: false } 
+                    })
+                };
+                const noPNApp = express();
+                noPNApp.use(httpRestHandler({ requestHandler: noPNRequestHandler as any }));
+
+                const response = await request(noPNApp)
+                    .post('/v1/tasks/task-1/pushNotificationConfigs')
+                    .send({ url: 'https://example.com/webhook', events: ['message'] })
+                    .expect(501);
 
-            assert.property(response.body, 'code');
-            assert.property(response.body, 'message');
-        });
+                assert.property(response.body, 'code');
+                assert.property(response.body, 'message');
+            });
         });
 
         describe('GET /v1/tasks/:taskId/pushNotificationConfigs', () => {
@@ -420,6 +432,21 @@ describe('httpRestHandler', () => {
                 .post('/v1/tasks/task-1:unknown')
                 .expect(404);
         });
+
+        it('should handle internal server errors gracefully', async () => {
+            (mockRequestHandler.sendMessage as SinonStub).rejects(
+                new Error('Unexpected internal error')
+            );
+
+            const response = await request(app)
+                .post('/v1/message:send')
+                .send({ message: testMessage })
+                .expect(500);
+
+            assert.property(response.body, 'code');
+            assert.property(response.body, 'message');
+            assert.equal(response.body.code, -32603); // Internal error code
+        });
     });
 });