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, TokioNetworkProvider, TokioTcpListener};
78pub use providers::{Providers, TokioProviders};
79pub use random::{RandomProvider, TokioRandomProvider};
80pub use storage::{
81 OpenOptions, StorageFile, StorageProvider, TokioStorageFile, TokioStorageProvider,
82};
83pub use task::{TaskProvider, TokioTaskProvider};
84pub use time::{TimeError, TimeProvider, TokioTimeProvider};
85
86// Core type exports
87pub use types::{Endpoint, NetworkAddress, NetworkAddressParseError, UID, flags};
88pub use well_known::{WELL_KNOWN_RESERVED_COUNT, WellKnownToken};