moonpool_core/lib.rs
1//! # moonpool-core
2//!
3//! Core abstractions for the moonpool simulation framework.
4//!
5//! This crate provides the foundational traits and types that enable
6//! moonpool's simulation capabilities. Application code depends on
7//! these abstractions rather than concrete implementations, allowing
8//! seamless switching between simulation and production environments.
9//!
10//! ## The Provider Pattern
11//!
12//! The key insight is that distributed systems interact with the outside
13//! world through a small set of operations: time, networking, task spawning,
14//! and randomness. By abstracting these behind traits, we can substitute
15//! deterministic simulation implementations during testing.
16//!
17//! ```text
18//! ┌──────────────────────────────────────────────────────┐
19//! │ Application Code │
20//! │ Uses: TimeProvider, NetworkProvider, etc. │
21//! └───────────────────────┬──────────────────────────────┘
22//! │ depends on traits
23//! ┌──────────────┴──────────────┐
24//! ▼ ▼
25//! ┌─────────────────┐ ┌─────────────────┐
26//! │ Simulation │ │ Production │
27//! │ SimTimeProvider │ │ TokioTimeProvider│
28//! │ SimNetworkProv. │ │ TokioNetworkProv.│
29//! │ (deterministic) │ │ (real I/O) │
30//! └─────────────────┘ └─────────────────┘
31//! ```
32//!
33//! ## Provider Traits
34//!
35//! | Trait | Simulation | Production | Purpose |
36//! |-------|------------|------------|---------|
37//! | [`TimeProvider`] | Logical time | Wall clock | Sleep, timeout, `now()` |
38//! | [`TaskProvider`] | Event-driven | Tokio spawn | Task spawning |
39//! | [`RandomProvider`] | Seeded RNG | System RNG | Deterministic randomness |
40//! | [`NetworkProvider`] | Simulated TCP | Real TCP | Connect, listen, accept |
41//! | [`StorageProvider`] | Fault-injected I/O | Real filesystem | File open, read, write, sync |
42//!
43//! **Important**: Never call tokio directly in application code.
44//! - ❌ `tokio::time::sleep()`
45//! - ✅ `time_provider.sleep()`
46//!
47//! ## Core Types
48//!
49//! Types for endpoint addressing:
50//!
51//! - [`UID`]: 128-bit unique identifier (deterministically generated in simulation)
52//! - [`Endpoint`]: Network address + token for direct addressing
53//! - [`NetworkAddress`]: IP address + port
54//! - [`WellKnownToken`]: Reserved tokens for system services
55
56#![deny(missing_docs)]
57#![deny(clippy::unwrap_used)]
58
59mod codec;
60mod error;
61mod network;
62mod providers;
63mod random;
64mod storage;
65mod task;
66mod time;
67mod types;
68mod well_known;
69
70// Codec exports
71pub use codec::{CodecError, JsonCodec, MessageCodec};
72
73// Error exports
74pub use error::{SimulationError, SimulationResult};
75
76// Provider trait exports
77pub use network::{NetworkProvider, TcpListenerTrait};
78#[cfg(feature = "tokio-providers")]
79pub use network::{TokioNetworkProvider, TokioTcpListener};
80pub use providers::Providers;
81#[cfg(feature = "tokio-providers")]
82pub use providers::TokioProviders;
83pub use random::RandomProvider;
84#[cfg(feature = "tokio-providers")]
85pub use random::TokioRandomProvider;
86pub use storage::{OpenOptions, StorageFile, StorageProvider};
87#[cfg(feature = "tokio-providers")]
88pub use storage::{TokioStorageFile, TokioStorageProvider};
89pub use task::{JoinError, TaskProvider};
90#[cfg(feature = "tokio-providers")]
91pub use task::{TokioJoinHandle, TokioTaskProvider};
92#[cfg(feature = "tokio-providers")]
93pub use time::TokioTimeProvider;
94pub use time::{TimeError, TimeProvider};
95
96// Core type exports
97pub use types::{Endpoint, NetworkAddress, NetworkAddressParseError, UID, flags};
98pub use well_known::{WELL_KNOWN_RESERVED_COUNT, WellKnownToken};