moonpool_sim/
lib.rs

1//! # Moonpool Simulation Framework
2//!
3//! Deterministic simulation for testing distributed systems, inspired by
4//! [FoundationDB's simulation testing](https://apple.github.io/foundationdb/testing.html).
5//!
6//! ## Why Deterministic Simulation?
7//!
8//! FoundationDB's insight: **bugs hide in error paths**. Production code rarely
9//! exercises timeout handlers, retry logic, or failure recovery. Deterministic
10//! simulation with fault injection finds these bugs before production does.
11//!
12//! Key properties:
13//! - **Reproducible**: Same seed produces identical execution
14//! - **Comprehensive**: Tests all failure modes (network, timing, corruption)
15//! - **Fast**: Logical time skips idle periods
16//!
17//! ## Core Components
18//!
19//! - [`SimWorld`]: The simulation runtime managing events and time
20//! - [`SimulationBuilder`]: Configure and run simulations
21//! - [`chaos`]: Fault injection (buggify, assertions, invariants)
22//!
23//! ## Quick Start
24//!
25//! ```ignore
26//! use moonpool_sim::{SimulationBuilder, WorkloadTopology};
27//!
28//! SimulationBuilder::new()
29//!     .topology(WorkloadTopology::ClientServer { clients: 2, servers: 1 })
30//!     .run(|ctx| async move {
31//!         // Your distributed system workload
32//!     });
33//! ```
34//!
35//! ## Fault Injection Overview
36//!
37//! See [`chaos`] module for detailed documentation.
38//!
39//! | Mechanism | Default | What it tests |
40//! |-----------|---------|---------------|
41//! | TCP latencies | 1-11ms connect | Async scheduling |
42//! | Random connection close | 0.001% | Reconnection, redelivery |
43//! | Bit flip corruption | 0.01% | Checksum validation |
44//! | Connect failure | 50% probabilistic | Timeout handling, retries |
45//! | Clock drift | 100ms max | Leases, heartbeats |
46//! | Buggified delays | 25% | Race conditions |
47//! | Partial writes | 1000 bytes max | Message fragmentation |
48//! | Packet loss | disabled | At-least-once delivery |
49//! | Network partitions | disabled | Split-brain handling |
50//!
51//! ## Multi-Seed Testing
52//!
53//! Tests run across multiple seeds to explore the state space:
54//!
55//! ```ignore
56//! SimulationBuilder::new()
57//!     .run_count(IterationControl::UntilAllSometimesReached(1000))
58//!     .run(workload);
59//! ```
60//!
61//! Debugging a failing seed:
62//!
63//! ```ignore
64//! SimulationBuilder::new()
65//!     .set_seed(failing_seed)
66//!     .run_count(IterationControl::FixedCount(1))
67//!     .run(workload);
68//! ```
69
70#![deny(missing_docs)]
71#![deny(clippy::unwrap_used)]
72
73// Re-export core types for convenience
74pub use moonpool_core::{
75    CodecError, Endpoint, JsonCodec, MessageCodec, NetworkAddress, NetworkAddressParseError,
76    NetworkProvider, RandomProvider, SimulationError, SimulationResult, TaskProvider,
77    TcpListenerTrait, TimeProvider, TokioNetworkProvider, TokioTaskProvider, TokioTimeProvider,
78    UID, WELL_KNOWN_RESERVED_COUNT, WellKnownToken,
79};
80
81// =============================================================================
82// Core Modules
83// =============================================================================
84
85/// Core simulation engine for deterministic testing.
86pub mod sim;
87
88/// Simulation runner and orchestration framework.
89pub mod runner;
90
91/// Chaos testing infrastructure for deterministic fault injection.
92pub mod chaos;
93
94/// Provider implementations for simulation.
95pub mod providers;
96
97/// Network simulation and configuration.
98pub mod network;
99
100// =============================================================================
101// Public API Re-exports
102// =============================================================================
103
104// Sim module re-exports
105pub use sim::{
106    ConnectionStateChange, Event, EventQueue, NetworkOperation, ScheduledEvent, SimWorld,
107    SleepFuture, WeakSimWorld, get_current_sim_seed, reset_sim_rng, set_sim_seed, sim_random,
108    sim_random_range, sim_random_range_or_default,
109};
110
111// Runner module re-exports
112pub use runner::{
113    IterationControl, SimulationBuilder, SimulationMetrics, SimulationReport, TokioReport,
114    TokioRunner, WorkloadTopology,
115};
116
117// Chaos module re-exports
118pub use chaos::{
119    AssertionStats, InvariantCheck, StateRegistry, buggify_init, buggify_reset,
120    get_assertion_results, panic_on_assertion_violations, reset_assertion_results,
121    validate_assertion_contracts,
122};
123
124// Network exports
125pub use network::{
126    ChaosConfiguration, ConnectFailureMode, NetworkConfiguration, SimNetworkProvider,
127    sample_duration,
128};
129
130// Provider exports
131pub use providers::{SimRandomProvider, SimTimeProvider};
132
133// Macros are automatically available at crate root when defined with #[macro_export]
moonpool_sim/lib.rs

moonpool_sim/
lib.rs
