@bcoders.gr/virtualpool/README.md

High-performance Ethereum testing framework with advanced provider pooling, adaptive load balancing, and comprehensive monitoring

# VirtualPool - High-Performance Ethereum Testing Framework

A high-performance Ethereum testing framework with advanced provider pooling, adaptive load balancing, and comprehensive monitoring.

## Features

- **Provider Pooling**: Manage multiple Anvil instances efficiently
- **Load Balancing**: Distribute requests across available providers
- **Health Monitoring**: Automatic health checks and provider recovery
- **Resource Management**: Efficient allocation and release of providers
- **Performance Metrics**: Comprehensive monitoring and statistics
- **Graceful Shutdown**: Clean resource cleanup and process management

## Installation

```bash
npm install @bcoders.gr/virtualpool
```

## Quick Start

```javascript
import { AnvilProviderPool } from '@bcoders.gr/virtualpool';

// Initialize pool with 3 providers (ports 8550-8552)
const pool = new AnvilProviderPool(8550, 8552);

// Initialize and get a provider
await pool.initialize();
const { provider, port } = await pool.getAvailableProvider();

// Use the provider
const blockNumber = await provider.request('eth_blockNumber');
console.log(`Current block: ${parseInt(blockNumber, 16)}`);

// Release the provider back to pool
pool.releaseProvider(port);

// Shutdown when done
await pool.shutdown();
```

## API Reference

### AnvilProviderPool

#### Constructor
```javascript
new AnvilProviderPool(portStart, portEnd, options)
```
- `portStart`: Starting port number (default: 8550)
- `portEnd`: Ending port number (default: 8560)
- `options`: Configuration options
  - `timeout`: Provider startup timeout (default: 30000ms)
  - `maxRetries`: Max retry attempts (default: 5)
  - `healthCheckInterval`: Health check frequency (default: 30000ms)
  - `maxParallelStarts`: Max concurrent provider starts (default: 5)

#### Methods

##### `initialize()`
Initialize the provider pool. Returns pool statistics.

##### `getAvailableProvider()`
Get an available provider from the pool.
- Returns: `{ provider, port }` or `null` if none available

##### `releaseProvider(port)`
Release a provider back to the pool.
- `port`: Port number of the provider to release

##### `getStats()`
Get comprehensive pool statistics.
- Returns: Object containing metrics like:
  - Total providers
  - Available/busy providers
  - Health status
  - Utilization rate
  - Request metrics

##### `shutdown()`
Gracefully shutdown the pool and cleanup resources.

##### `withProvider(fn)`
Execute a function with an automatically managed provider.
```javascript
await pool.withProvider(async (provider) => {
    const block = await provider.request('eth_blockNumber');
    return block;
});
```

##### `withProviderStrategy(fn, strategy)`
Execute a function with a provider selected by strategy.
- Strategies: 'random', 'roundRobin', 'leastUsed', 'fastest'

## Health Monitoring

The pool automatically:
- Monitors provider health
- Restarts unhealthy providers
- Implements circuit breaker patterns
- Collects performance metrics
- Manages provider lifecycle

## Performance Features

- Concurrent provider initialization
- Request batching and caching
- Adaptive load balancing
- Resource pooling
- Connection management
- Error recovery
- Performance metrics

## Example

See [examples/basic-usage.js](examples/basic-usage.js) for a complete example.

## Testing

Run the comprehensive test suite:

```bash
npm test
```

## License

MIT