turmoil

Turmoil is split into several specialized crates depending on the level of simulation required:

• turmoil: The full simulation-testing framework. This is the primary entry point for users.
• turmoil-net: A deterministic simulated socket stack. It is designed as a drop-in replacement for tokio::net.
• turmoil-fs: A deterministic simulated filesystem. It is designed as a drop-in replacement for std::fs or tokio::fs.
• turmoil-io-uring: A deterministic simulated io_uring. It includes an optional fs feature that integrates it with turmoil-fs.

The turmoil crate serves as the full-stack entry point for the turmoil ecosystem. It bundles a runtime, a simulated network, and a simulated filesystem behind a single Builder. Use this crate if you want a complete, ready-to-use simulation harness.

If you are assembling a custom runtime and do not need the full bundle, you should instead use turmoil-net for networking or turmoil-fs for filesystem simulation directly.

[dev-dependencies]
turmoil = "0.7"

turmoil-io-uring is a simulated implementation of the io_uring interface designed for deterministic testing in Rust. It is intended to allow developers to run code that normally relies on the Linux io_uring kernel interface on other platforms like macOS or Windows within a Turmoil simulation.

Key Characteristics:

• API Parity: It closely mirrors the io-uring 0.7 crate API. You can often swap use io_uring::*; for use turmoil_io_uring::*; via feature flags.
• Simulated Execution: It is not a real kernel interface. There are no syscalls or memory-mapped rings. Instead, Submission Queue Entries (SQEs) are queued in per-host Rust state, and Completion Queue Entries (CQEs) are made observable as simulated time advances.
• Platform Agnostic: Enables testing of io_uring-based logic in environments without a Linux kernel.

Turmoil is a family of crates designed for deterministic simulation testing of distributed systems. It allows you to run multiple concurrent hosts within a single thread, enabling you to simulate complex distributed environments reliably.

Key capabilities include:

• Deterministic Simulation: Runs multiple hosts in a single thread to ensure reproducible test runs.
• Hardship Injection: You can manually control or use a seeded RNG to inject network and filesystem failures such as:
  • Latency
  • Packet drops
  • Network partitions
  • Node crashes
  • Torn writes

turmoil-net provides a deterministic, simulated socket stack for testing async Rust code. Instead of using real OS sockets which are nondeterministic due to timing and scheduling, you use a shim that implements real protocols (handshake, FIN, RST, MSS, backpressure) on a controlled substrate.

To use it, swap your tokio::net imports for turmoil_net::shim::tokio::net imports using #[cfg] attributes in your code. This allows the same logic to run against real networking in production and a simulated network during tests.

#[cfg(not(test))]
use tokio::net::TcpStream;
#[cfg(test)]
use turmoil_net::shim::tokio::net::TcpStream;

The barriers feature (currently unstable) allows tests to observe and control specific points in the code under test.

By using a trigger(event) call in your production code (which is conditionally compiled), the execution will block until the test resolves that specific event. This enables deterministic scheduling of arbitrary events without needing to thread them through the network layer.

Note: This requires enabling the unstable-barriers feature.

Unlike a standard mock that simply returns primed bytes, turmoil-fs models the distinction between data in the page cache and data on stable storage:

1. Writes: Land in a per-host 'pending' state.
2. fsync: Promotes pending writes to a 'durable' state.
3. Simulated Crash: Discards the pending state, simulating data loss for writes that were not yet synced.

By using a seeded RNG to drive the interleaving of pending/sync operations, you can create deterministic and replayable crash-consistency tests.

turmoil-fs provides a simulated filesystem designed for testing async Rust code deterministically. It allows you to simulate crash-consistency scenarios (like failures between write and fsync) by explicitly modeling the split between pending writes and durable storage.

To use it, you swap standard library or tokio filesystem imports for turmoil_fs::shim imports using #[cfg(test)]. This allows the same production code to run against a controlled, simulated filesystem during testing.

Supported shim modules:

• turmoil_fs::shim::std (Standard library replacements)
• turmoil_fs::shim::tokio (Tokio replacements)

#[cfg(not(test))]
use std::fs::OpenOptions;
#[cfg(test)]
use turmoil_fs::shim::std::fs::OpenOptions;

To run the example demonstrating how to set up axum using the turmoil simulation runtime, use the following command:

$ cargo run -p axum-example

To see detailed debug information while running the gRPC example, set the RUST_LOG environment variable to debug:

RUST_LOG=debug cargo run -p grpc

To use the simulated io_uring interface, you should typically consume it through the turmoil umbrella crate using the unstable-io_uring feature flag. This integrates the simulated ring into the broader Turmoil simulation environment.

For specific integration patterns, refer to the turmoil crate documentation.

To see detailed logs while running the axum-example, set the RUST_LOG environment variable to debug:

$ RUST_LOG=debug cargo run -p axum-example