@dexwox-labs/a2a-server
Version:
TypeScript server implementation for Google's Agent-to-Agent (A2A) protocol - includes Express/WebSocket handlers, request validation and queue management
161 lines • 6.11 kB
TypeScript
/**
* @module DefaultJsonRpcRequestHandler
* @description Default implementation of the JSON-RPC request handler for the A2A protocol
*
* This module provides the default implementation of the JSON-RPC request handler
* interface for the A2A protocol server. It includes middleware for request validation,
* error handling, and response formatting, as well as methods for handling various
* JSON-RPC requests.
*/
import { Request, Response } from 'express';
import { JsonRpcRequestHandler } from './jsonrpc-handler';
import { JsonRpcResponse } from '@dexwox-labs/a2a-core';
import { z } from 'zod';
import { Middleware } from './base-handler';
/**
* Default implementation of the JSON-RPC request handler
*
* This class provides a standard implementation of the JSON-RPC request handler
* interface for the A2A protocol server. It includes middleware for request
* validation, error handling, and response formatting, as well as methods for
* handling various JSON-RPC requests.
*
* @example
* ```typescript
* // Create a JSON-RPC request handler
* const jsonRpcHandler = new DefaultJsonRpcRequestHandler();
*
* // Add middleware
* jsonRpcHandler.use(jsonRpcHandler.handleErrors());
* jsonRpcHandler.use(jsonRpcHandler.formatResponse());
*
* // Use in an Express app
* app.use('/jsonrpc', jsonRpcHandler.router);
* ```
*/
export declare class DefaultJsonRpcRequestHandler implements JsonRpcRequestHandler {
/** Express router for handling HTTP requests */
readonly router: import("express-serve-static-core").Router;
/** Array of middleware functions to apply to requests */
private middlewares;
/**
* Adds middleware to the request handler
*
* This method adds a middleware function to the request handler's middleware
* stack. Middleware functions are executed in the order they are added.
*
* @param middleware - Middleware function to add
*
* @example
* ```typescript
* // Add error handling middleware
* jsonRpcHandler.use(jsonRpcHandler.handleErrors());
*
* // Add custom logging middleware
* jsonRpcHandler.use(async (req, res, next) => {
* console.log(`${req.method} ${req.path}`);
* await next();
* });
* ```
*/
use(middleware: Middleware): void;
/**
* Creates middleware for validating request body against a schema
*
* This method returns a middleware function that validates the request body
* against a Zod schema. If validation fails, it responds with a 400 Bad Request
* and a JSON-RPC error response.
*
* @param schema - Zod schema to validate against
* @returns Middleware function that validates requests
*
* @example
* ```typescript
* // Create a schema for validating sendMessage requests
* const sendMessageSchema = z.object({
* jsonrpc: z.literal('2.0'),
* method: z.literal('sendMessage'),
* params: z.object({
* parts: z.array(z.object({
* type: z.string(),
* content: z.string()
* })),
* agentId: z.string()
* }),
* id: z.string().optional()
* });
*
* // Add validation middleware
* jsonRpcHandler.use(jsonRpcHandler.validateRequest(sendMessageSchema));
* ```
*/
validateRequest(schema: z.ZodSchema): Middleware;
/**
* Creates middleware for handling errors
*
* This method returns a middleware function that catches any errors thrown
* during request processing and responds with a 500 Internal Server Error
* and a JSON-RPC error response.
*
* @returns Middleware function that catches and processes errors
*
* @example
* ```typescript
* // Add error handling middleware
* jsonRpcHandler.use(jsonRpcHandler.handleErrors());
* ```
*/
handleErrors(): Middleware;
/**
* Creates middleware for formatting responses
*
* This method returns a middleware function that formats responses as JSON-RPC
* success responses. If the response already has a jsonrpc property, it is
* left unchanged.
*
* @returns Middleware function that formats responses
*
* @example
* ```typescript
* // Add response formatting middleware
* jsonRpcHandler.use(jsonRpcHandler.formatResponse());
* ```
*/
formatResponse(): Middleware;
/**
* Builds a JSON-RPC success response
*
* This method creates a properly formatted JSON-RPC 2.0 success response
* with the provided result data.
*
* @param id - Request ID from the original JSON-RPC request
* @param result - Result data to include in the response
* @returns Properly formatted JSON-RPC success response
*
* @example
* ```typescript
* // Create a success response
* const response = jsonRpcHandler.buildSuccessResponse('request-123', {
* taskId: 'task-456'
* });
*
* // Send the response
* res.json(response);
* ```
*/
buildSuccessResponse(id?: string | number, result?: any): JsonRpcResponse;
buildErrorResponse(id?: string | number, error?: any): JsonRpcResponse;
handleJsonRpcSendMessage(req: Request, res: Response): Promise<void>;
handleJsonRpcStreamMessage(req: Request, res: Response): Promise<void>;
handleJsonRpcGetTaskStatus(req: Request, res: Response): Promise<void>;
handleJsonRpcCancelTask(req: Request, res: Response): Promise<void>;
handleJsonRpcDiscoverAgents(req: Request, res: Response): Promise<void>;
handleSendMessage(parts: any[], agentId: string): Promise<string>;
handleStreamMessage(parts: any[], agentId: string): AsyncGenerator<any, void, unknown>;
handleGetTaskStatus(taskId: string): Promise<any>;
handleCancelTask(taskId: string): Promise<void>;
handleTaskResubscription(taskId: string): AsyncGenerator<any, void, unknown>;
handleDiscoverAgents(capability?: string): Promise<any>;
normalizeError(err: unknown): any;
}
//# sourceMappingURL=default-jsonrpc-handler.d.ts.map