Crate prism3_retry 

Prism3 Retry - Retry module

A fully-featured, type-safe retry management system, ported from Java’s ltd.qubit.commons.util.retry package to Rust.

Design Philosophy

Core Design Principles

1. Type Safety First - Leverage Rust’s type system to ensure type safety at compile time
2. Result Error Handling - Use Rust’s Result type for error handling instead of exceptions
3. Zero-Cost Abstraction - Use enums instead of trait objects to avoid dynamic dispatch overhead
4. Unified Interface - Provide generic APIs that support all primitive types and custom types
5. Event-Driven - Support various event listeners during the retry process

Module Structure

retry/
|-- mod.rs              # Module entry point, exports public API
|-- builder.rs           # RetryBuilder struct (core retry builder)
|-- config.rs            # RetryConfig trait and DefaultRetryConfig
|-- delay_strategy.rs    # RetryDelayStrategy enum
|-- events.rs            # Event type definitions
|-- error.rs             # Error type definitions
|-- executor.rs          # RetryExecutor executor

Core Features

• ✅ Type-Safe Retry - Use generic API to support any return type
• ✅ Multiple Delay Strategies - Support fixed delay, random delay, exponential backoff
• ✅ Flexible Error Handling - Result-based error handling with error type identification
• ✅ Result-Driven Retry - Support retry logic based on return values
• ✅ Event Listening - Support various event callbacks during retry process
• ✅ Configuration Integration - Seamless integration with prism3-config’s config module
• ✅ Timeout Control - Support single operation timeout and overall timeout control
• ✅ Sync and Async - Support both synchronous and asynchronous operation retries

Usage Examples

Basic Synchronous Retry

use prism3_retry::{RetryBuilder, RetryDelayStrategy, RetryResult, RetryEvent};
use std::time::Duration;

// Basic retry configuration
let executor = RetryBuilder::new()
    .set_max_attempts(3)
    .set_delay_strategy(RetryDelayStrategy::Fixed { delay: Duration::from_secs(1) })
    .failed_on_results(vec!["RETRY".to_string(), "TEMP_FAIL".to_string()])
    .on_retry(|event: &RetryEvent<String>| println!("Retry attempt {}", event.attempt_count()))
    .build();

// Use RetryResult type alias to simplify return type
let result: RetryResult<String> = executor.run(|| -> Result<String, Box<dyn std::error::Error + Send + Sync>> {
    // Can use ? operator, io::Error will be automatically converted to
    // RetryError through From trait
    // Example: std::fs::read_to_string("config.txt")?;
    Ok("SUCCESS".to_string())
});

assert!(result.is_ok());

Async Retry with Timeout Control

use prism3_retry::{RetryBuilder, RetryResult};
use std::time::Duration;

// Configure timeout control
let executor = RetryBuilder::<String>::new()
    .set_max_attempts(3)
    .set_operation_timeout(Some(Duration::from_secs(5)))  // Max 5 seconds per operation
    .set_max_duration(Some(Duration::from_secs(30)))      // Max 30 seconds total
    .build();

// Use RetryResult to simplify async function return type
let result: RetryResult<String> = executor.run_async(|| async {
    // Async operation timeout will be truly interrupted
    // Can use ? operator, errors will be automatically converted
    // Example: tokio::fs::read_to_string("config.txt").await?;
    Ok("SUCCESS".to_string())
}).await;

assert!(result.is_ok());

For detailed usage, please refer to the documentation of each struct.

Author

Haixing Hu

Re-exports

pub use builder::RetryBuilder;

pub use config::RetryConfig;

pub use default_config::DefaultRetryConfig;

pub use delay_strategy::RetryDelayStrategy;

pub use error::RetryError;

pub use event::AbortEvent;

pub use event::AbortReason;

pub use event::FailureEvent;

pub use event::RetryDecision;

pub use event::RetryEvent;

pub use event::RetryReason;

pub use event::SuccessEvent;

pub use executor::RetryExecutor;

pub use simple_config::SimpleRetryConfig;

Modules

builder

Retry Builder

config

Retry Configuration Interface

default_config

Default Retry Configuration Implementation

delay_strategy

Retry Delay Strategy

error

Retry Error Types

event

Retry Event Module

executor

Retry Executor

simple_config

Simple Retry Configuration Implementation

Type Aliases

DefaultRetryBuilder

Type alias for retry builder using default configuration

DefaultRetryExecutor

Type alias for retry executor using default configuration

RetryResult