Moonpool

Deterministic simulation testing for distributed systems in Rust. Write your distributed system once, test it with deterministic simulation and chaos injection, then deploy with real networking — using identical application code.

Inspired by FoundationDB's simulation testing and Antithesis.

Note: This is a hobby-grade project under active development.

Architecture

moonpool                          Facade crate, re-exports everything
├── moonpool-transport            RPC, peer connections, wire format
│   └── moonpool-transport-derive #[service] proc-macro
├── moonpool-sim                  Simulation engine, chaos testing, assertions
│   └── moonpool-explorer         Fork-based multiverse exploration
└── moonpool-core                 Provider traits and core types

Which Crate to Use

Key Features

• Provider pattern — Application code depends on traits (TimeProvider, NetworkProvider, TaskProvider, RandomProvider, StorageProvider), not concrete implementations. Same code runs in simulation and production.
• Deterministic simulation — Same seed = identical execution. Logical time skips idle periods. Years of uptime simulated in seconds.
• Chaos testing — Network delays, disconnects, partitions, bit flips, partial writes, storage corruption. buggify! fires with 25% probability at fault injection points.
• Assertion suite — 15 Antithesis-style assertion macros (assert_always!, assert_sometimes!, numeric comparisons, compound assertions). Multi-seed testing runs until all sometimes assertions fire.
• Fork-based exploration — When assertions discover new behavior, fork() explores alternate timelines with different RNG seeds. Adaptive energy budgets and coverage bitmaps guide exploration.
• #[service] macro — Auto-generates RPC server/client boilerplate from a single trait definition.

Quick Start

# Enter development environment (Nix required)
nix develop

# Run tests
nix develop --command cargo nextest run

# Build documentation
nix develop --command cargo doc --open

Documentation

• The Sim Book — User guide covering philosophy, architecture, and practical details
• API Documentation — Rustdoc with architecture diagrams and usage examples
• Repository

License

Apache 2.0