ethereum-rpc-docker/split-proxy

ETH JSON-RPC Proxy (Dual Upstream Comparator)

A high-performance Ethereum JSON-RPC proxy that forwards requests to two upstream endpoints, streams responses from the primary, and compares responses for latency and content differences.

Features

• 🚀 Streaming Response: Streams response from primary endpoint with minimal latency
• 🔍 Dual Comparison: Compares responses from two endpoints in parallel
• 📊 Latency Monitoring: Tracks and logs latency differences between endpoints
• 🔧 Configurable Roles: Switch primary/secondary roles via configuration
• 🔄 Dynamic Role Switching: Switch primary/secondary roles at runtime without restart
• 📝 Structured Logging: JSON-formatted logs for easy parsing and monitoring
• 🐳 Docker Ready: Includes Dockerfile for easy deployment

Quick Start

Local Development

1. Install dependencies:

npm install

2. Copy the example environment file:

cp .env.example .env

3. Configure your RPC endpoints in .env:

PRIMARY_RPC=http://localhost:8545
SECONDARY_RPC=http://localhost:8546

4. Start the proxy:

npm start

For development with auto-reload:

npm run dev

Docker

Build and run with Docker:

# Build the image
docker build -t eth-rpc-proxy .

# Run the container
docker run -p 8545:8545 \
  -e PRIMARY_RPC=http://your-primary-rpc:8545 \
  -e SECONDARY_RPC=http://your-secondary-rpc:8545 \
  eth-rpc-proxy

Configuration

All configuration is done via environment variables:

Variable	Default	Description
PRIMARY_RPC	http://localhost:8545	Primary RPC endpoint URL
SECONDARY_RPC	http://localhost:8546	Secondary RPC endpoint URL
PRIMARY_ROLE	primary	Which endpoint to stream (primary or secondary)
LATENCY_THRESHOLD_MS	1000	Log if secondary is slower by this many ms
SIZE_DIFF_THRESHOLD	100	Log full response if size differs by this many bytes
LOG_MISMATCHES	true	Whether to log response mismatches
PORT	8545	Port to listen on
REQUEST_TIMEOUT	30000	Request timeout in milliseconds
LOG_LEVEL	info	Log level (debug, info, warn, error)
DNS_REFRESH_INTERVAL	1000	DNS cache refresh interval in milliseconds

Usage Examples

Basic JSON-RPC Request

curl -X POST http://localhost:8545 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "eth_blockNumber",
    "params": [],
    "id": 1
  }'

Health Check

curl http://localhost:8545/health

Response:

{
  "status": "ok",
  "primaryEndpoint": "http://localhost:8545",
  "secondaryEndpoint": "http://localhost:8546",
  "primaryRole": "primary"
}

How It Works

1. Request Reception: Proxy receives JSON-RPC POST request
2. Parallel Forwarding: Request is sent to both primary and secondary endpoints simultaneously
3. Stream Response: Response from the designated primary is streamed back to client immediately
4. Background Comparison: Secondary response is collected and compared in the background
5. Logging: Differences in latency, size, or content are logged for monitoring

Dynamic Role Switching

You can switch between primary and secondary endpoints at runtime without restarting the proxy by sending a SIGUSR1 signal:

Local Process

# Find the process ID
ps aux | grep "node index.js"

# Send SIGUSR1 signal
kill -USR1 <pid>

Docker Container

# Send SIGUSR1 to the container
docker kill -s USR1 eth-rpc-proxy

# Or if using docker-compose
docker-compose kill -s USR1 eth-rpc-proxy

When the signal is received, the proxy will:

• Swap the streaming and comparison endpoints
• Log the role switch with the new configuration
• Continue processing requests with the new roles immediately

The health endpoint will reflect the current active endpoints:

{
  "status": "ok",
  "primaryEndpoint": "http://localhost:8545",
  "secondaryEndpoint": "http://localhost:8546",
  "primaryRole": "secondary",
  "currentStreamEndpoint": "http://localhost:8546",
  "currentCompareEndpoint": "http://localhost:8545"
}

DNS Resolution for Docker Environments

The proxy automatically handles DNS resolution to ensure it always connects to the correct container IPs, even when containers restart and receive new IP addresses. This is especially important in Docker environments.

How it works:

1. Fresh DNS Lookups: The proxy creates new HTTP clients for each request, ensuring fresh DNS resolution
2. Periodic Cache Clearing: DNS cache is cleared at the configured interval (default: 1 second)
3. Connection Pooling: Despite fresh DNS lookups, connections are pooled for performance
4. Automatic Recovery: When a container restarts with a new IP, the proxy automatically discovers it

Configuration:

Set the DNS_REFRESH_INTERVAL environment variable to control how often the DNS cache is refreshed:

# Refresh DNS every second (default)
DNS_REFRESH_INTERVAL=1000

# Refresh DNS every 5 seconds
DNS_REFRESH_INTERVAL=5000

This ensures the proxy remains resilient in dynamic container environments where services may be redeployed or scaled.

Monitoring

The proxy logs structured JSON output that includes:

• Request IDs for tracing
• Method names
• Latency measurements
• Response sizes
• Mismatch details

Example log output:

{
  "level": "info",
  "time": "2024-01-01T12:00:00.000Z",
  "requestId": "a1b2c3d4e5f6",
  "method": "eth_getBlockByNumber",
  "endpoint": "stream",
  "latencyMs": 45,
  "msg": "Stream response started"
}

Performance Considerations

• The proxy streams responses to minimize latency impact
• Comparison happens asynchronously without blocking the response
• Large responses are handled efficiently with streaming
• Connection pooling is used for upstream requests

Docker Compose Example

version: '3.8'

services:
  eth-proxy:
    build: .
    ports:
      - "8545:8545"
    environment:
      PRIMARY_RPC: http://geth:8545
      SECONDARY_RPC: http://besu:8545
      LATENCY_THRESHOLD_MS: 500
      LOG_LEVEL: info
    restart: unless-stopped

Troubleshooting

Common Issues

1. Connection Refused: Ensure upstream endpoints are accessible
2. Timeout Errors: Increase REQUEST_TIMEOUT for slow endpoints
3. Memory Issues: The proxy buffers secondary responses - ensure adequate memory for large responses

Debug Mode

Enable debug logging for more detailed information:

LOG_LEVEL=debug npm start

License

MIT