Crate fallibles

Crate fallibles 

Source
Expand description

§fallibles

Fallibles enables controlled failure injection for testing error handling in Rust applications. Mark functions with #[fallible] and configure when they should fail for comprehensive testing.

§Quick Start

use fallibles::*;

#[fallible]
fn database_query() -> Result<String, &'static str> {
    Ok("data".to_string())
}

// Enable 30% failure rate
fallibles_core::configure_failures(
    fallibles_core::FailureConfig::new().with_probability(0.3)
);

§Examples

§Basic Usage

use fallibles::*;

#[fallible]
fn read_config() -> Result<i32, &'static str> {
    Ok(42)
}

// Without config, function always succeeds
assert_eq!(read_config().unwrap(), 42);

// Enable failures with RAII guard
{
    let _guard = fallibles_core::with_config(
        fallibles_core::FailureConfig::new().with_probability(1.0)
    );
    // Now it will fail
    assert!(read_config().is_err());
} // Config automatically cleared

§Inline Configuration

use fallibles::*;

#[fallible(probability = 0.2)]  // 20% failure rate
fn flaky_api() -> Result<String, &'static str> {
    Ok("response".to_string())
}

#[fallible(trigger_every = 5)]  // Fail every 5th call
fn periodic_task() -> Result<(), String> {
    Ok(())
}

§Policy-Based Testing

use fallibles::fallibles_core::{FailureConfig, with_config};

// Chaos Monkey: 10% random failures
let _guard = with_config(FailureConfig::chaos_monkey());

// Degraded Service: 30% failures
let _guard = with_config(FailureConfig::degraded_service(0.3));

// Circuit Breaker: fail every 5th call
let _guard = with_config(FailureConfig::circuit_breaker(5));

§Conditional Failures

use fallibles::fallibles_core::{FailureConfig, with_config};

// Only fail when environment variable is set
let _guard = with_config(
    FailureConfig::new()
        .with_probability(0.5)
        .when(|| std::env::var("CHAOS_MODE").is_ok())
);

§Reproducible Testing

use fallibles::fallibles_core::{FailureConfig, with_config};

// Same seed always produces same failure pattern
let _guard = with_config(
    FailureConfig::new()
        .with_probability(0.3)
        .with_seed(12345)
);
// Or from environment: FALLIBLE_SEED=12345 cargo test

§Custom Error Types

use fallibles::*;

#[derive(Debug, FallibleError)]
#[fallible(message = "timeout occurred")]
struct TimeoutError {
    message: String,
}

#[fallible]
fn network_call() -> Result<String, TimeoutError> {
    Ok("data".to_string())
}

§Features

  • fallible-sim - Enable failure injection (required)
  • std - Standard library support (default)
  • anyhow - Support for anyhow::Error
  • eyre - Support for eyre::Report

Re-exports§

pub extern crate fallibles_core;
pub extern crate fxhash;

Structs§

FailureConfig
Configuration for failure injection behavior.
FailureConfigGuard
Automatically clears configuration when dropped.
FailurePoint
Information about a specific failure point.
FailurePointId
Unique identifier for a failure point.
FailureStats
Statistics about failure behavior.
PanicHandler

Traits§

FailureHandler
Handler trait for custom failure behavior.
FallibleError
Trait for error types that can be generated during simulated failures.

Functions§

clear_failure_config
Clear global configuration.
clear_thread_failure_config
Clear thread-local configuration.
configure_failures
Set global configuration.
configure_thread_failures
Set thread-local configuration.
get_failure_stats
Get statistics about the current configuration.
set_global_handler
Set a custom global failure handler.
should_simulate_failure
Check if a failure should be simulated at this point.
with_config
Set global failure configuration with automatic cleanup.
with_thread_config
Set thread-local failure configuration with automatic cleanup.

Type Aliases§

FailureCallback
Callback function type for observability hooks.
FailurePredicate
Predicate function type for conditional failure injection.

Attribute Macros§

fallible
Mark a function for failure injection.

Derive Macros§

FallibleError
Derive the FallibleError trait for custom error types.