RPCProxyConfig

Documentation for eth_defi.provider.rpc_proxy.RPCProxyConfig Python class.

class RPCProxyConfig

Bases: object

Configuration for the JSON-RPC failover proxy.

Collects all tuneable parameters of start_rpc_proxy() into a single object with sensible defaults. Every field has a docstring explaining its purpose, default value, and interaction with other fields.

You can construct this directly and pass it to start_rpc_proxy(), or pass it as the proxy_multiple_upstream argument to launch_anvil().

Example — standalone proxy with custom configuration:

from eth_defi.provider.rpc_proxy import RPCProxyConfig, start_rpc_proxy

config = RPCProxyConfig(
    timeout=15.0,
    retries=5,
    auto_switch_request_count=50,
)
proxy = start_rpc_proxy(
    ["https://rpc-a.example.com", "https://rpc-b.example.com"],
    config=config,
)

Example — passing to launch_anvil:

from eth_defi.provider.anvil import launch_anvil
from eth_defi.provider.rpc_proxy import RPCProxyConfig

config = RPCProxyConfig(timeout=10.0, retries=4)
launch = launch_anvil(
    fork_url="https://rpc-a.example.com https://rpc-b.example.com",
    proxy_multiple_upstream=config,
)

See also RPCProxy, start_rpc_proxy(), default_failure_handler().

Attributes summary

name

Human-readable name for this proxy instance.

timeout

Per-upstream-attempt timeout in seconds.

retries

Maximum number of upstream attempts per incoming request.

backoff

Initial sleep duration in seconds between retry attempts.

auto_switch_request_count

Number of successful requests to serve from one provider before automatically switching to the next in round-robin order.

switchover_log_level

Logging level for upstream failure and switchover events.

request_log_level

Logging level for request/response payload dumping.

log_max_size

Maximum byte size for logged request/response payloads.

pool_maxsize

Maximum number of connections per host in the HTTP pool.

max_error_replies

Maximum number of error replies stored per provider in UpstreamRPCProviderStatistics.error_replies.

failure_handler

Custom failure detection callback.

suppress_client_disconnect_errors

Suppress downstream client disconnect tracebacks.

Methods summary

__init__([name, timeout, retries, backoff, ...])

describe()

Return a human-readable summary of the configuration for logging.
name: Optional[str]

Human-readable name for this proxy instance.

Used in log messages and as the background thread name to help identify which proxy is reporting when multiple proxies run concurrently (e.g. one per chain). If None, a default name is generated from the port number.

timeout: float

Per-upstream-attempt timeout in seconds.

Each individual request to an upstream RPC provider will be aborted after this duration. Set lower than the typical caller timeout (90 s) to leave room for failover attempts. For example, with the default of 30 s and 3 retries, the worst-case wall-clock time per incoming request is ~90 s — matching Anvil’s typical read timeout.

retries: int

Maximum number of upstream attempts per incoming request.

The proxy cycles through available providers up to this many times before giving up and returning an HTTP 502 with a JSON-RPC error body to the caller. Each attempt targets the next provider in round-robin order (or the same provider if only one is configured).

backoff: float

Initial sleep duration in seconds between retry attempts.

Grows by 1.5× after each retry (e.g. 0.5 → 0.75 → 1.125 …). Kept short because retries typically switch to a different provider, so there is no benefit in waiting for the same provider to recover.

auto_switch_request_count: int

Number of successful requests to serve from one provider before automatically switching to the next in round-robin order.

Set to 0 (the default) to disable auto-switching — the proxy will only switch providers on errors. Setting a positive value helps distribute load across providers and can detect degraded providers early by exercising all of them regularly.

switchover_log_level: int

Logging level for upstream failure and switchover events.

Each time the proxy encounters a retryable error or switches to another upstream provider, it logs a message at this level. Defaults to logging.INFO so failures are visible in normal operation. Set to logging.WARNING or logging.DEBUG to adjust verbosity.

request_log_level: int

Logging level for request/response payload dumping.

When the effective logger level is at or below this threshold, the proxy logs the full JSON-RPC request body before forwarding and the full response body after receiving it. This is useful for debugging but generates significant output.

When the logger level is above this threshold the formatting is skipped entirely — zero overhead in production. Defaults to logging.DEBUG.

log_max_size: int

Maximum byte size for logged request/response payloads.

Payloads larger than this are truncated with a "… (truncated, total N bytes)" suffix. Prevents massive eth_getCode or debug_traceTransaction responses from flooding log files.

pool_maxsize: int

Maximum number of connections per host in the HTTP pool.

Anvil can issue many concurrent requests during genesis fork creation, so a larger pool avoids Connection pool is full, discarding connection warnings from urllib3.

max_error_replies: int

Maximum number of error replies stored per provider in UpstreamRPCProviderStatistics.error_replies.

Oldest entries are discarded when this limit is reached, keeping memory bounded during long-running proxy sessions.

failure_handler: Callable[[int, Optional[dict]], bool]

Custom failure detection callback.

Called with (http_status, parsed_json_body) for every upstream response. Must return True if the response should be treated as a retryable failure (triggering a switch to the next provider).

Connection-level failures (timeouts, refused connections) bypass this handler and are always retried.

Defaults to default_failure_handler(), which replicates the battle-tested error classification from eth_defi.middleware.

suppress_client_disconnect_errors: bool

Suppress downstream client disconnect tracebacks.

Used by Anvil fork tests where Anvil can close in-flight proxy requests during process shutdown. Direct proxy users keep the default strict behaviour so unexpected client disconnects are still visible.

describe()

Return a human-readable summary of the configuration for logging.

Includes all tuneable numeric fields for full visibility.

Example output:

timeout=30.0, retries=3, backoff=0.5, auto_switch_request_count=0, pool_maxsize=50, max_error_replies=100, log_max_size=2048
Return type

str

__init__(name=None, timeout=30.0, retries=3, backoff=0.5, auto_switch_request_count=0, switchover_log_level=20, request_log_level=10, log_max_size=2048, pool_maxsize=50, max_error_replies=100, failure_handler=None, suppress_client_disconnect_errors=False)
Parameters
Return type

None