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//!
42//! **Important**: Never call tokio directly in application code.
43//! - ❌ `tokio::time::sleep()`
44//! - ✅ `time_provider.sleep()`
45//!
46//! ## Core Types
47//!
48//! FDB-compatible types for endpoint addressing:
49//!
50//! - [`UID`]: 128-bit unique identifier (deterministically generated in simulation)
51//! - [`Endpoint`]: Network address + token for direct addressing
52//! - [`NetworkAddress`]: IP address + port
53//! - [`WellKnownToken`]: Reserved tokens for system services
54
55#![deny(missing_docs)]
56#![deny(clippy::unwrap_used)]
57
58mod codec;
59mod error;
60mod network;
61mod random;
62mod task;
63mod time;
64mod types;
65mod well_known;
66
67// Codec exports
68pub use codec::{CodecError, JsonCodec, MessageCodec};
69
70// Error exports
71pub use error::{SimulationError, SimulationResult};
72
73// Provider trait exports
74pub use network::{NetworkProvider, TcpListenerTrait, TokioNetworkProvider, TokioTcpListener};
75pub use random::RandomProvider;
76pub use task::{TaskProvider, TokioTaskProvider};
77pub use time::{TimeProvider, TokioTimeProvider};
78
79// Core type exports
80pub use types::{Endpoint, NetworkAddress, NetworkAddressParseError, UID, flags};
81pub use well_known::{WELL_KNOWN_RESERVED_COUNT, WellKnownToken};