moonpool-core 0.6.0

Core abstractions for the moonpool simulation framework
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90

//! # moonpool-core
//!
//! Core abstractions for the moonpool simulation framework.
//!
//! This crate provides the foundational traits and types that enable
//! moonpool's simulation capabilities. Application code depends on
//! these abstractions rather than concrete implementations, allowing
//! seamless switching between simulation and production environments.
//!
//! ## The Provider Pattern
//!
//! The key insight is that distributed systems interact with the outside
//! world through a small set of operations: time, networking, task spawning,
//! and randomness. By abstracting these behind traits, we can substitute
//! deterministic simulation implementations during testing.
//!
//! ```text
//! ┌──────────────────────────────────────────────────────┐
//! │                 Application Code                      │
//! │     Uses: TimeProvider, NetworkProvider, etc.         │
//! └───────────────────────┬──────────────────────────────┘
//!                         │ depends on traits
//!          ┌──────────────┴──────────────┐
//!          ▼                             ▼
//!   ┌─────────────────┐         ┌─────────────────┐
//!   │   Simulation    │         │   Production    │
//!   │ SimTimeProvider │         │ TokioTimeProvider│
//!   │ SimNetworkProv. │         │ TokioNetworkProv.│
//!   │ (deterministic) │         │  (real I/O)     │
//!   └─────────────────┘         └─────────────────┘
//! ```
//!
//! ## Provider Traits
//!
//! | Trait | Simulation | Production | Purpose |
//! |-------|------------|------------|---------|
//! | [`TimeProvider`] | Logical time | Wall clock | Sleep, timeout, now() |
//! | [`TaskProvider`] | Event-driven | Tokio spawn | Task spawning |
//! | [`RandomProvider`] | Seeded RNG | System RNG | Deterministic randomness |
//! | [`NetworkProvider`] | Simulated TCP | Real TCP | Connect, listen, accept |
//! | [`StorageProvider`] | Fault-injected I/O | Real filesystem | File open, read, write, sync |
//!
//! **Important**: Never call tokio directly in application code.
//! - ❌ `tokio::time::sleep()`
//! - ✅ `time_provider.sleep()`
//!
//! ## Core Types
//!
//! Types for endpoint addressing:
//!
//! - [`UID`]: 128-bit unique identifier (deterministically generated in simulation)
//! - [`Endpoint`]: Network address + token for direct addressing
//! - [`NetworkAddress`]: IP address + port
//! - [`WellKnownToken`]: Reserved tokens for system services

#![deny(missing_docs)]
#![deny(clippy::unwrap_used)]

mod codec;
mod error;
mod network;
mod node_address;
mod providers;
mod random;
mod storage;
mod task;
mod time;
mod types;
mod well_known;

// Codec exports
pub use codec::{CodecError, JsonCodec, MessageCodec};

// Error exports
pub use error::{SimulationError, SimulationResult};

// Provider trait exports
pub use network::{NetworkProvider, TcpListenerTrait, TokioNetworkProvider, TokioTcpListener};
pub use providers::{Providers, TokioProviders};
pub use random::{RandomProvider, TokioRandomProvider};
pub use storage::{
    OpenOptions, StorageFile, StorageProvider, TokioStorageFile, TokioStorageProvider,
};
pub use task::{TaskProvider, TokioTaskProvider};
pub use time::{TimeError, TimeProvider, TokioTimeProvider};

// Core type exports
pub use node_address::NodeAddress;
pub use types::{Endpoint, NetworkAddress, NetworkAddressParseError, UID, flags};
pub use well_known::{WELL_KNOWN_RESERVED_COUNT, WellKnownToken};