Crate moonpool_core 

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.

┌──────────────────────────────────────────────────────┐
│                 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

Important: Never call tokio directly in application code.

• ❌ tokio::time::sleep()
• ✅ time_provider.sleep()

Core Types

FDB-compatible 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

Modules

flags

Address flags (FDB-compatible).

Structs

Endpoint

Endpoint = Address + Token (FDB-compatible).

JsonCodec

JSON codec using serde_json.

NetworkAddress

Network address (IPv4/IPv6 + port + flags).

TokioNetworkProvider

Real Tokio networking 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 (FDB-compatible).

Enums

CodecError

Error type for codec operations.

NetworkAddressParseError

Error parsing a network address from string.

SimulationError

Errors that can occur during simulation operations.

WellKnownToken

Well-known endpoint tokens (FDB-compatible pattern).

Constants

WELL_KNOWN_RESERVED_COUNT

Number of reserved well-known token slots.

Traits

MessageCodec

Pluggable message serialization format.

NetworkProvider

Provider trait for creating network connections and listeners.

RandomProvider

Provider trait for random number generation.

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.

Type Aliases

SimulationResult

A type alias for Result<T, SimulationError>.