@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
252 lines • 8.35 kB
TypeScript
/**
* @module QueueManager
* @description Interface and types for managing event queues in the A2A protocol
*
* This module provides interfaces and types for managing the lifecycle of event
* queues in the A2A protocol server. It defines the QueueManager interface and
* related types for queue statistics and errors.
*/
import { EventQueue } from '../agent-execution/event-queue';
import { A2AError } from '@dexwox-labs/a2a-core';
/**
* Interface for managing event queue lifecycles
*
* The QueueManager interface defines the contract for managing event queues
* in the A2A protocol server. It provides methods for creating, retrieving,
* tapping into, and closing event queues for tasks.
*
* @example
* ```typescript
* // Create a queue manager
* const queueManager = new InMemoryQueueManager();
*
* // Create or get a queue for a task
* const queue = await queueManager.createOrGet('task-123');
*
* // Subscribe to events on the queue
* queue.subscribe(event => {
* console.log(`Event: ${event.type} for task ${event.task.id}`);
* });
*
* // Tap into the queue to create a new consumer
* const tapQueue = await queueManager.tap('task-123');
*
* // Close the queue when done
* await queueManager.close('task-123');
* ```
*/
export interface QueueManager {
/**
* Adds a new queue for a task
*
* This method registers a new event queue for a specific task.
* It throws an error if a queue already exists for the task.
*
* @param taskId - ID of the task to add a queue for
* @param queue - The event queue to add
* @returns Promise that resolves when the queue is added
* @throws {QueueExistsError} If a queue already exists for the task
*
* @example
* ```typescript
* const queue = new EventQueue();
* try {
* await queueManager.add('task-123', queue);
* console.log('Queue added successfully');
* } catch (error) {
* if (error instanceof QueueExistsError) {
* console.error('Queue already exists for this task');
* }
* }
* ```
*/
add(taskId: string, queue: EventQueue): Promise<void>;
/**
* Gets an existing queue for a task
*
* This method retrieves the event queue for a specific task.
* It returns undefined if no queue exists for the task.
*
* @param taskId - ID of the task to get the queue for
* @returns Promise resolving to the event queue, or undefined if not found
*
* @example
* ```typescript
* const queue = await queueManager.get('task-123');
* if (queue) {
* console.log('Found queue for task');
* // Use the queue
* } else {
* console.log('No queue found for task');
* }
* ```
*/
get(taskId: string): Promise<EventQueue | undefined>;
/**
* Creates a new queue or gets an existing one
*
* This method retrieves the event queue for a specific task if it exists,
* or creates a new one if it doesn't. It's a convenience method that
* combines the functionality of add and get.
*
* @param taskId - ID of the task to get or create a queue for
* @returns Promise resolving to the existing or newly created event queue
*
* @example
* ```typescript
* // Get or create a queue for a task
* const queue = await queueManager.createOrGet('task-123');
*
* // Use the queue
* queue.subscribe(event => {
* console.log(`Received event: ${event.type}`);
* });
* ```
*/
createOrGet(taskId: string): Promise<EventQueue>;
/**
* Taps into an existing queue to create a new consumer
*
* This method creates a new event queue that receives copies of all events
* published to the original queue for a specific task. It's useful for
* creating specialized event handlers or for filtering events.
*
* @param taskId - ID of the task to tap the queue for
* @returns Promise resolving to a new event queue that receives copies of events
* @throws {NoQueueError} If no queue exists for the task
*
* @example
* ```typescript
* try {
* // Create a specialized queue for completed tasks
* const tapQueue = await queueManager.tap('task-123');
*
* // Subscribe to events on the tapped queue
* tapQueue.subscribe(event => {
* if (event.type === 'taskCompleted') {
* // Handle completed tasks
* console.log('Task completed:', event.task.id);
* }
* });
* } catch (error) {
* if (error instanceof NoQueueError) {
* console.error('No queue exists for this task');
* }
* }
* ```
*/
tap(taskId: string): Promise<EventQueue>;
/**
* Closes and removes a queue
*
* This method shuts down the event queue for a specific task and removes
* it from the manager. After calling this method, the queue will no longer
* receive or publish events.
*
* @param taskId - ID of the task to close the queue for
* @returns Promise that resolves when the queue is closed and removed
*
* @example
* ```typescript
* // When done with a task's queue
* await queueManager.close('task-123');
* console.log('Queue closed and removed');
* ```
*/
close(taskId: string): Promise<void>;
/**
* Gets statistics for a queue
*
* This method retrieves statistics about the event queue for a specific task,
* such as the number of events, consumers, and performance metrics.
*
* @param taskId - ID of the task to get queue statistics for
* @returns Promise resolving to queue statistics
*
* @example
* ```typescript
* const stats = await queueManager.getStats('task-123');
* console.log('Queue size:', stats.size);
* console.log('Number of consumers:', stats.consumers);
* console.log('Events processed:', stats.processed);
* console.log('Error rate:', stats.errorRate);
* ```
*/
getStats(taskId: string): Promise<QueueStats>;
}
/**
* Statistics for an event queue
*
* This interface defines the structure of statistics for an event queue,
* including metrics about queue size, consumers, processing performance,
* and error rates.
*/
export interface QueueStats {
/** Current number of events in the queue */
size: number;
/** Number of consumers subscribed to the queue */
consumers: number;
/** Total number of events processed by the queue */
processed: number;
/** Number of events that failed processing */
failed: number;
/** Timestamp of the last activity on the queue */
lastActivity: Date;
/** Events processed per second */
throughput: number;
/** Average time to process an event in milliseconds */
avgProcessingTime: number;
/** Ratio of failed events to total processed events */
errorRate: number;
}
/**
* Error thrown when attempting to add a queue that already exists
*
* This error is thrown when trying to add a new queue for a task that
* already has a queue registered with the queue manager.
*
* @example
* ```typescript
* try {
* await queueManager.add('task-123', new EventQueue());
* } catch (error) {
* if (error instanceof QueueExistsError) {
* console.error('Cannot add queue:', error.message);
* }
* }
* ```
*/
export declare class QueueExistsError extends A2AError {
/**
* Creates a new QueueExistsError
*
* @param taskId - ID of the task that already has a queue
*/
constructor(taskId: string);
}
/**
* Error thrown when attempting to access a queue that doesn't exist
*
* This error is thrown when trying to access or tap into a queue for a task
* that doesn't have a queue registered with the queue manager.
*
* @example
* ```typescript
* try {
* await queueManager.tap('task-123');
* } catch (error) {
* if (error instanceof NoQueueError) {
* console.error('Cannot tap queue:', error.message);
* }
* }
* ```
*/
export declare class NoQueueError extends A2AError {
/**
* Creates a new NoQueueError
*
* @param taskId - ID of the task that doesn't have a queue
*/
constructor(taskId: string);
}
//# sourceMappingURL=queue-manager.d.ts.map