Crate moonpool

Expand description

§Moonpool

Deterministic simulation testing for distributed systems in Rust.

Moonpool enables you to write distributed system logic once, test it with simulated networking for reproducible debugging, then deploy with real networking—all using identical application code.

Inspired by FoundationDB’s simulation testing.

§Crate Architecture

┌─────────────────────────────────────────────────────────────┐
│              moonpool (this crate)                          │
│   Re-exports all functionality + virtual actors module      │
├──────────────────────────┬──────────────────────────────────┤
│  moonpool-transport      │       moonpool-sim               │
│  • Peer connections      │       • SimWorld runtime         │
│  • Wire format           │       • Chaos testing            │
│  • NetTransport + RPC    │       • Buggify macros           │
│  • #[service] macro      │       • 14 assertion macros      │
│    (via transport-derive)│       • Multiverse exploration   │
│                          │         (via moonpool-explorer)  │
├──────────────────────────┴──────────────────────────────────┤
│                     moonpool-core                           │
│  Provider traits: Time, Task, Network, Random, Storage      │
│  Core types: UID, Endpoint, NetworkAddress                  │
└─────────────────────────────────────────────────────────────┘

§Quick Start

use moonpool::{SimulationBuilder, WorkloadTopology};

SimulationBuilder::new()
    .topology(WorkloadTopology::ClientServer { clients: 2, servers: 1 })
    .run(|ctx| async move {
        // Your distributed system workload
    });

§Which Crate to Use

Use case	Crate
Full framework (recommended)	`moonpool`
Provider traits only	`moonpool-core`
Simulation without transport	`moonpool-sim`
Transport without simulation	`moonpool-transport`
Fork-based exploration internals	`moonpool-explorer`
Proc-macro internals	`moonpool-transport-derive`

§Documentation

moonpool_core - Provider traits and core types
moonpool_sim - Simulation runtime and chaos testing
moonpool_transport - Network transport layer
actors - Virtual actor system (Orleans-style)

Modules§

actors: Virtual actor networking layer for moonpool.
chaos: Chaos testing infrastructure for deterministic fault injection. Chaos testing infrastructure for deterministic fault injection.
error: Error types for transport operations. Error types for the moonpool messaging layer.
flags: Address flags.
network: Network simulation and configuration. Network simulation and configuration.
peer: Resilient peer connection management. Resilient peer connection management.
providers: Provider implementations for simulation. Provider implementations for simulation.
rpc: RPC layer with typed request/response patterns. FDB-style static messaging with fixed endpoints.
runner: Simulation runner and orchestration framework. Simulation runner and orchestration framework.
sim: Core simulation engine for deterministic testing. Core simulation engine for deterministic testing.
simulations: Simulation workloads for chaos testing and exploration.
storage: Storage simulation and configuration. Storage simulation and configuration.
wire: Wire format with CRC32C checksums. Wire format for packet serialization.

Macros§

assert_always: Assert that a condition is always true.
assert_always_greater_than: Assert that val > threshold always holds.
assert_always_greater_than_or_equal_to: Assert that val >= threshold always holds.
assert_always_less_than: Assert that val < threshold always holds.
assert_always_less_than_or_equal_to: Assert that val <= threshold always holds.
assert_always_or_unreachable: Assert that a condition is always true when reached, but the code path need not be reached. Does not panic if never evaluated.
assert_reachable: Assert that a code path is reachable (should be reached at least once).
assert_sometimes: Assert a condition that should sometimes be true, tracking stats and triggering exploration.
assert_sometimes_all: Compound boolean assertion: all named bools should sometimes be true simultaneously.
assert_sometimes_each: Per-value bucketed sometimes assertion with optional quality watermarks.
assert_sometimes_greater_than: Assert that val > threshold sometimes holds. Forks on watermark improvement.
assert_sometimes_greater_than_or_equal_to: Assert that val >= threshold sometimes holds. Forks on watermark improvement.
assert_sometimes_less_than: Assert that val < threshold sometimes holds. Forks on watermark improvement.
assert_sometimes_less_than_or_equal_to: Assert that val <= threshold sometimes holds. Forks on watermark improvement.
assert_unreachable: Assert that a code path should never be reached.
buggify: Buggify with 25% probability
buggify_with_prob: Buggify with custom probability

Structs§

AdaptiveConfig: Configuration for adaptive batch-based timeline splitting.
AssertionStats: Statistics for a tracked assertion.
Attrition: Built-in attrition configuration for automatic process reboots.
BugRecipe: A captured bug recipe with its root seed for deterministic replay.
ChaosConfiguration: Configuration for chaos injection in simulations.
Endpoint: Endpoint = Address + Token.
EndpointMap: Maps endpoint tokens to message receivers.
EventQueue: A priority queue for scheduling events in chronological order.
ExplorationConfig: Configuration for exploration.
ExplorationReport: Report from fork-based exploration.
FailureMonitor: Reactive failure monitor for address and endpoint tracking.
FaultContext: Context for fault injectors — gives access to SimWorld fault injection methods.
InMemoryStorage: In-memory storage with deterministic fault injection.
JsonCodec: JSON codec using serde_json.
MonitorConfig: Configuration for connection health monitoring.
NetNotifiedQueue: Type-safe message queue with async notification.
NetTransport: Central transport coordinator (FDB NetTransport equivalent).
NetTransportBuilder: Builder for NetTransport that eliminates common footguns.
NetworkAddress: Network address (IPv4/IPv6 + port + flags).
NetworkConfiguration: Configuration for network simulation parameters
NodeAddress: Identifies a specific node instance in the cluster.
OpenOptions: Options for opening a file.
PacketHeader: Packet header for wire format.
Peer: A resilient peer that manages connections to a remote address.
PeerConfig: Configuration for peer behavior and reconnection parameters.
PeerMetrics: Metrics and state information for a peer connection.
PhaseConfig: Two-phase simulation configuration.
ProcessTags: Resolved tags for a specific process instance.
ReplyFuture: Future that resolves when a reply is received from the server.
ReplyPromise: Promise for sending a reply to a request.
RequestEnvelope: Envelope wrapping a request with its reply endpoint.
RequestStream: Stream for receiving typed requests with reply promises.
ScheduledEvent: An event scheduled for execution at a specific simulation time.
SectorBitSet: A simple bitset for tracking sector states.
ServerHandle: Handle for a running RPC server.
SimContext: Simulation context provided to workloads.
SimNetworkProvider: Simulated networking implementation
SimProviders: Simulation providers bundle for deterministic testing.
SimRandomProvider: Random provider for simulation that uses the thread-local deterministic RNG.
SimStorageProvider: Simulated storage provider for deterministic testing.
SimTimeProvider: Simulation time provider that integrates with SimWorld.
SimWorld: The central simulation coordinator that manages time and event processing.
SimulationBuilder: Builder pattern for configuring and running simulation experiments.
SimulationMetrics: Core metrics collected during a simulation run.
SimulationReport: Comprehensive report of a simulation run with statistical analysis.
SleepFuture: Future that completes after a specified simulation time duration.
StateHandle: Shared state handle for cross-workload communication and invariant checking.
StorageConfiguration: Configuration for storage simulation parameters.
TagRegistry: Registry mapping process IPs to their resolved tags.
TokioNetworkProvider: Real Tokio networking implementation.
TokioProviders: Production providers using Tokio runtime.
TokioRandomProvider: Production random provider using thread-local RNG.
TokioReport: Report generated after running workloads with TokioRunner.
TokioRunner: Builder for executing workloads with real Tokio implementations.
TokioStorageFile: Wrapper for Tokio File to implement our trait.
TokioStorageProvider: Real Tokio storage implementation.
TokioTaskProvider: Tokio-based task provider using spawn_local for single-threaded execution.
TokioTcpListener: Wrapper for Tokio TcpListener to implement our trait.
TokioTimeProvider: Real time provider using Tokio’s time facilities.
UID: 128-bit unique identifier.
WeakSimWorld: A weak reference to a simulation world.
WorkloadTopology: Topology information provided to workloads and processes.

Enums§

AssertCmp: Comparison operator for numeric assertions.
AssertKind: The kind of assertion being tracked.
ClientId: Strategy for assigning client IDs to workload instances.
CodecError: Error type for codec operations.
ConnectFailureMode: Connection establishment failure mode for fault injection.
ConnectionStateChange: Connection state changes
Event: Events that can be scheduled in the simulation.
FailedReason: Reason an endpoint was permanently marked as failed.
FailureStatus: Status of a network address or endpoint.
IterationControl: Configuration for how many iterations a simulation should run.
MessagingError: Errors that can occur in the messaging layer.
NetworkAddressParseError: Error parsing a network address from string.
NetworkOperation: Network data operations
Parallelism: Controls how many children can run in parallel during splitting.
PeerError: Errors that can occur during peer operations.
RebootKind: The type of reboot to perform on a process.
ReplyError: Errors that can occur during request-response operations.
RpcError: Unified error type for RPC operations.
SimulationError: Errors that can occur during simulation operations.
StorageOperation: Storage operations that can be scheduled in the simulation.
TimeError: Errors that can occur during time operations.
WellKnownToken: Well-known endpoint tokens.
WireError: Wire format error types.
WorkloadCount: How many instances of a workload to spawn per iteration.

Constants§

HEADER_SIZE: Header size: 4 (length) + 4 (checksum) + 16 (token) = 24 bytes.
MAX_PAYLOAD_SIZE: Maximum payload size (1MB).
SECTOR_SIZE: Size of a disk sector in bytes.
WELL_KNOWN_RESERVED_COUNT: Number of reserved well-known token slots.

Traits§

FaultInjector: A fault injector that introduces failures during the chaos phase.
Invariant: An invariant that validates system-wide properties during simulation.
MessageCodec: Pluggable message serialization format.
MessageReceiver: Trait for receiving deserialized messages from the transport layer.
NetworkProvider: Provider trait for creating network connections and listeners.
Process: A process that participates in simulation as part of the system under test.
Providers: Bundle of all provider types for a runtime environment.
RandomProvider: Provider trait for random number generation.
StorageFile: Trait for file handles that support async read/write/seek operations.
StorageProvider: Provider trait for file storage operations.
TaskProvider: Provider for spawning local tasks in single-threaded context.
TcpListenerTrait: Trait for TCP listeners that can accept connections.
TimeProvider: Provider trait for time operations.
Workload: A workload that participates in simulation testing.

Functions§

buggify_init: Initialize buggify for simulation run
buggify_reset: Reset/disable buggify
clear_rng_breakpoints: Clear all RNG breakpoints.
deserialize_packet: Deserialize a packet, validating checksum.
format_timeline: Format a recipe as a human-readable timeline string.
get_assertion_results: Get current assertion statistics for all tracked assertions.
get_current_sim_seed: Get the current simulation seed.
get_reply: At-least-once delivery: send reliably, retransmit on reconnect.
get_reply_unless_failed_for: At-least-once delivery with sustained failure timeout.
get_rng_call_count: Get the current RNG call count.
has_always_violations: Check whether any always-type assertion was violated during this iteration.
invariant_fn: Create an invariant from a closure.
method_endpoint: Generate method endpoint from base endpoint and index.
method_uid: Generate UID for a specific interface method.
panic_on_assertion_violations: Panic if the report contains assertion violations.
parse_timeline: Parse a timeline string back into a recipe.
reset_always_violations: Reset the violation counter. Must be called at the start of each iteration.
reset_assertion_results: Reset all assertion statistics.
reset_rng_call_count: Reset the RNG call count to zero.
reset_sim_rng: Reset the thread-local simulation RNG to a fresh state.
sample_duration: Sample a random duration from a range
send: Fire-and-forget delivery: send request unreliably with no reply.
send_request: Send a typed request and return a future for the response.
serialize_packet: Serialize a packet with token and payload.
set_rng_breakpoints: Set RNG breakpoints for deterministic replay.
set_sim_seed: Set the seed for the thread-local simulation RNG.
sim_random: Generate a random value using the thread-local simulation RNG.
sim_random_range: Generate a random value within a specified range using the thread-local simulation RNG.
sim_random_range_or_default: Generate a random value within the given range, returning the start value if the range is empty.
try_deserialize_packet: Try to deserialize from a buffer that may contain partial data.
try_get_reply: At-most-once delivery: send unreliably, race reply against disconnect.
validate_assertion_contracts: Validate all assertion contracts based on their kind.

Type Aliases§

PeerReceiver: Type alias for the peer receiver channel. Used when taking ownership via take_receiver().
SimulationResult: A type alias for Result<T, SimulationError>.

Attribute Macros§

actor_impl: Attribute macro for auto-generating ActorHandler boilerplate.
service: Unified attribute macro for defining RPC interfaces and virtual actors.

Crate moonpool

Crate moonpool Copy item path

§Moonpool

§Crate Architecture

§Quick Start

§Which Crate to Use

§Documentation

Modules§

Macros§

Structs§

Enums§

Constants§

Traits§

Functions§

Type Aliases§

Attribute Macros§

Crate moonpool