@dexwox-labs/a2a-client
Version:
TypeScript client implementation for Google's Agent-to-Agent (A2A) protocol - includes HTTP/WebSocket communication, circuit breakers and error handling
132 lines • 4.33 kB
TypeScript
/**
* @module CircuitBreaker
* @description Circuit breaker implementation for improving reliability in network operations
*/
/**
* Configuration options for the circuit breaker
*
* These options control the behavior of the circuit breaker, including
* when it opens, when it attempts to close, and how many successes are
* required to fully close it again.
*
* @example
* ```typescript
* const options: CircuitBreakerOptions = {
* failureThreshold: 3, // Open after 3 consecutive failures
* successThreshold: 2, // Close after 2 consecutive successes
* timeout: 10000 // Wait 10 seconds before attempting to close
* };
* ```
*/
export interface CircuitBreakerOptions {
/** Number of consecutive failures before opening the circuit */
failureThreshold: number;
/** Number of consecutive successes required to close the circuit */
successThreshold: number;
/** Time in milliseconds to wait before attempting to close the circuit */
timeout: number;
}
/**
* Circuit breaker implementation for improving reliability
*
* The circuit breaker pattern prevents cascading failures by temporarily disabling
* operations that are likely to fail.
*
* @example
* ```typescript
* const breaker = new CircuitBreaker({
* failureThreshold: 3,
* successThreshold: 2,
* timeout: 10000
* });
*
* const result = await breaker.execute(async () => {
* return await fetch('https://api.example.com/data');
* });
* ```
*/
export declare class CircuitBreaker {
/** @private Current state of the circuit breaker */
private state;
/** @private Count of consecutive failures */
private failureCount;
/** @private Count of consecutive successes in HALF_OPEN state */
private successCount;
/** @private Timestamp of the last failure */
private lastFailureTime;
/** @private Configuration options */
private readonly options;
/**
* Creates a new circuit breaker instance
*
* @param options - Configuration options for the circuit breaker
*/
constructor(options: CircuitBreakerOptions);
/**
* Executes a function with circuit breaker protection
*
* This method wraps the provided function with circuit breaker logic.
* If the circuit is closed, the function executes normally. If the circuit
* is open, an error is thrown immediately without executing the function.
* If the circuit is half-open, the function is executed as a test to see
* if the underlying system has recovered.
*
* @param fn - The async function to execute
* @returns Promise resolving to the result of the function
* @throws {A2AError} If the circuit is open
* @throws Any error thrown by the executed function
*
* @example
* ```typescript
* try {
* const data = await breaker.execute(async () => {
* const response = await fetch('https://api.example.com/data');
* return response.json();
* });
* processData(data);
* } catch (error) {
* if (error.code === -32050) {
* console.error('Circuit is open, not attempting request');
* } else {
* console.error('Request failed:', error);
* }
* }
* ```
*/
execute<T>(fn: () => Promise<T>): Promise<T>;
/**
* Handles successful operations
*
* Resets the failure count and, if in HALF_OPEN state, increments the success count.
* If enough consecutive successes occur in HALF_OPEN state, the circuit is closed.
*
* @private
*/
private onSuccess;
/**
* Handles failed operations
*
* Increments the failure count and records the time of failure.
* If enough consecutive failures occur, the circuit is opened.
*
* @private
*/
private onFailure;
/**
* Gets the current state of the circuit breaker
*
* @returns The current state: 'CLOSED', 'OPEN', or 'HALF_OPEN'
*
* @example
* ```typescript
* const state = breaker.getState();
* console.log(`Circuit breaker is currently ${state}`);
*
* if (state === 'OPEN') {
* console.log('Circuit is open, requests will be rejected');
* }
* ```
*/
getState(): string;
}
//# sourceMappingURL=circuit-breaker.d.ts.map