Crate faultkit 

faultkit: Internet-scale fault injection for testing complex error paths and edge cases.

Inspired by SQLite’s OOM and IO error injection, faultkit lets you fail the Nth call to a specific operation and verify the system handles it gracefully. It is designed for maximum performance, robustness at scale, and comprehensive test coverage.

WHAT this crate does

faultkit provides a zero-cost abstraction for injecting targeted failures (like allocation errors, I/O errors, or channel send failures) into your system’s critical paths. It manages global, atomic state tracking fail conditions and triggers failures probabilistically, persistently, or on precise counts.

WHY someone would use it

Testing happy paths is trivial, but ensuring an internet-scale system gracefully handles an OOM or a disconnected network socket during a million-file write requires deterministic fault injection. faultkit forces these errors natively without requiring cumbersome stubs or mocks.

HOW to get started

use faultkit::{inject, clear, should_fail_mmap, Fault};

// Make the 3rd mmap call fail
let _ = inject(Fault::Mmap { fail_after: 3 });

// ... in your code ...
if should_fail_mmap() {
    // return simulated error
}

// Clean up
let _ = clear();

Compile-time control

Fault injection is always available. The state check is completely zero-cost when not active, enabling the compiler to optimize the check away in hot paths.

Structs

ClearedFaults

Summary of faults cleared by a clear operation.

FaultGuard

RAII guard for fault injection.

Enums

Fault

Fault types that can be injected.

InjectionError

Error when injecting a fault.

Operation

Operations that can be failed via injection.

Functions

clear

Clear all injected faults and return what was cleared.

inject

Inject a fault.

inject_scoped

Inject a fault and return an RAII guard that clears faults on drop.

is_enabled

Check if fault injection is enabled globally.

should_fail_alloc

Check if an allocation should fail.

should_fail_mmap

Check if an mmap call should fail. Call this at instrumented mmap sites.

should_fail_read

Check if a read call should fail.

should_fail_send

Check if a channel send should fail.

should_fail_write

Check if a write call should fail.

try_inject

Inject a fault. Appends to existing fail points if the fault type allows multiple.