Struct FailureSchedule 

pub struct FailureSchedule { /* private fields */ }

A schedule that decides whether a given attempt fails.

Schedules are deterministic by default. The same (schedule, attempt) pair produces the same outcome across runs and machines.

Example

use dev_chaos::{FailureMode, FailureSchedule};

let s = FailureSchedule::on_attempts(&[2, 4], FailureMode::IoError);
assert!(s.maybe_fail(1).is_ok());
assert!(s.maybe_fail(2).is_err());

Implementations

impl FailureSchedule

pub fn on_attempts(attempts: &[usize], mode: FailureMode) -> Self

Build a schedule that fails on specific attempt numbers (1-indexed).

Example

use dev_chaos::{FailureMode, FailureSchedule};
let s = FailureSchedule::on_attempts(&[3, 7], FailureMode::Timeout);
assert!(s.maybe_fail(3).is_err());
assert!(s.maybe_fail(4).is_ok());

pub fn every_n(n: usize, mode: FailureMode) -> Self

Build a schedule that fails on every Nth attempt (1-indexed).

Example

use dev_chaos::{FailureMode, FailureSchedule};
let s = FailureSchedule::every_n(3, FailureMode::Timeout);
assert!(s.maybe_fail(3).is_err());
assert!(s.maybe_fail(6).is_err());

pub fn seeded_random(seed: u64, probability: f64, mode: FailureMode) -> Self

Build a deterministic, seeded “random” schedule.

Each attempt is hashed (with the seed) into a value in [0, 1000) and fails when that value is below probability * 1000. The schedule is fully reproducible from the seed.

probability is clamped to [0.0, 1.0].

This is the only non-explicit schedule. Even so, it is strictly reproducible; no real RNG state, no clock, no thread.

Example

use dev_chaos::{FailureMode, FailureSchedule};

let a = FailureSchedule::seeded_random(42, 0.10, FailureMode::IoError);
let b = FailureSchedule::seeded_random(42, 0.10, FailureMode::IoError);
// Same seed => same outcome at every attempt.
for attempt in 1..=100 {
    assert_eq!(a.maybe_fail(attempt).is_err(), b.maybe_fail(attempt).is_err());
}

pub fn limit(self, n: usize) -> Self

Cap the total number of failures this schedule will emit.

After n failures have been emitted via maybe_fail, the schedule stops firing — every subsequent call returns Ok(()), regardless of attempt number.

Useful for bounded chaos: you want a few failures to verify recovery, not an indefinite stream.

Example

use dev_chaos::{FailureMode, FailureSchedule};

// Fail every attempt, but stop after 3.
let s = FailureSchedule::every_n(1, FailureMode::IoError).limit(3);
let mut failures = 0;
for attempt in 1..=20 {
    if s.maybe_fail(attempt).is_err() {
        failures += 1;
    }
}
assert_eq!(failures, 3);

pub fn maybe_fail(&self, attempt: usize) -> Result<(), InjectedFailure>

Check whether the given attempt should fail.

Returns Ok(()) if the operation should proceed, or Err(InjectedFailure) if the schedule fires on this attempt.

If a limit has been applied and the failure count has reached it, this returns Ok(()) regardless of whether the schedule would otherwise fire.

pub fn failure_count(&self) -> usize

Total failures emitted by this schedule so far.

pub fn invocation_count(&self) -> usize

Total invocations of maybe_fail since this schedule was built.

pub fn mode(&self) -> FailureMode

Mode this schedule injects.