cpex-retry-with-backoff 0.3.0

High-performance retry and backoff policy engine for MCP Gateway

Retry With Backoff (Rust)

High-performance retry and backoff policy engine for ContextForge and MCP Gateway.

Features

• Rust-backed retry state tracking for tool invocations
• Exponential backoff with optional jitter
• Per-tool policy overrides without duplicating whole plugin configs
• Retry decisions based on isError, structured status_code, or optional parsed text payloads
• Automatic state eviction for stale request entries
• Gateway ceiling enforcement for max_retries
• Retry policy metadata returned on tool and resource hooks

Build

make install

Runtime Requirements

This plugin depends on cpex>=0.1.0rc1,<0.2 and imports hook models from cpex.framework. The compiled Rust extension is mandatory; there is no Python fallback implementation.

Usage

The plugin runs on tool_post_invoke and resource_post_fetch.

Typical uses:

• Retry transient upstream failures such as 429, 500, 502, 503, and 504
• Clamp aggressive plugin settings to the gateway-wide retry ceiling
• Apply stricter retry budgets to fragile or expensive tools

Configuration

Core settings

• max_retries: maximum retry attempts before giving up
• backoff_base_ms: base delay for exponential backoff
• max_backoff_ms: upper bound for computed retry delays
• retry_on_status: HTTP or structured status codes treated as retriable
• jitter: randomize delay within the current exponential ceiling
• check_text_content: inspect text content for JSON-encoded error payloads when structured content is absent

Per-tool overrides

Use tool_overrides to change retry behavior for a specific tool:

• max_retries
• backoff_base_ms
• max_backoff_ms
• retry_on_status
• jitter

Behavior Notes

• Successful responses clear retry state for the (tool, request_id) pair.
• Retry state expires after a short TTL so abandoned request state does not accumulate indefinitely.
• If check_text_content is disabled, the hot path uses the Rust state manager directly.
• If check_text_content is enabled, Python-side payload inspection supplements the Rust state manager before applying retry policy.

Returned Metadata

Both tool and resource hooks emit retry policy metadata so downstream systems can observe the active policy:

• max_retries
• backoff_base_ms
• max_backoff_ms
• retry_on_status

Testing

# Full plugin CI
make ci

Performance

The retry state manager is implemented in Rust so the common retry decision path avoids Python bookkeeping overhead for normal structured tool results.