nautilus_network/
dst.rs

1// -------------------------------------------------------------------------------------------------
2//  Copyright (C) 2015-2026 Nautech Systems Pty Ltd. All rights reserved.
3//  https://nautechsystems.io
4//
5//  Licensed under the GNU Lesser General Public License Version 3.0 (the "License");
6//  You may not use this file except in compliance with the License.
7//  You may obtain a copy of the License at https://www.gnu.org/licenses/lgpl-3.0.en.html
8//
9//  Unless required by applicable law or agreed to in writing, software
10//  distributed under the License is distributed on an "AS IS" BASIS,
11//  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12//  See the License for the specific language governing permissions and
13//  limitations under the License.
14// -------------------------------------------------------------------------------------------------
15
16//! Deterministic simulation testing (DST) seam for network async primitives.
17//!
18//! Re-exports time-related async primitives so every call site in
19//! `nautilus-network` routes through one cfg-gated location. Under
20//! `simulation` + `cfg(madsim)`, re-exports from `madsim::time` so waits and
21//! timeouts advance with madsim's virtual clock. Otherwise re-exports from
22//! `tokio::time`.
23//!
24//! `Instant` is routed the same way so that `now()` reads and `sleep`/`timeout`
25//! waits share a single clock base. Using `tokio::time::Instant` on normal
26//! builds keeps the seam compatible with `#[tokio::test(start_paused = true)]`
27//! tests that drive time via `tokio::time::advance`.
28//!
29//! `nautilus-network` sits below `nautilus-common` in the dependency graph and
30//! cannot import from `nautilus_common::live::dst`, which is why this helper
31//! is crate-local.
32
33pub mod time {
34    pub use std::time::Duration;
35
36    #[cfg(all(feature = "simulation", madsim))]
37    pub use madsim::time::{Instant, sleep, timeout};
38    #[cfg(not(all(feature = "simulation", madsim)))]
39    pub use tokio::time::{Instant, sleep, timeout};
40}
41
42#[cfg(test)]
43mod tests {
44    use super::*;
45
46    // Under madsim, `time::Instant` and `time::sleep` both run on the virtual
47    // clock with sub-ms scheduling epsilon. If the cfg gate fell through to
48    // real tokio, `sleep` would block on the OS scheduler with ~5-15ms of
49    // jitter and the tight upper bound would fail.
50    #[cfg(all(feature = "simulation", madsim))]
51    #[madsim::test]
52    async fn test_dst_sleep_uses_virtual_time() {
53        let start = time::Instant::now();
54        time::sleep(time::Duration::from_millis(100)).await;
55        let elapsed = start.elapsed();
56        assert!(elapsed >= time::Duration::from_millis(100));
57        assert!(
58            elapsed < time::Duration::from_millis(101),
59            "virtual sleep showed real-tokio jitter: {elapsed:?}"
60        );
61    }
62
63    // Mirror under real tokio (paused clock) to keep both routes exercised.
64    #[cfg(not(all(feature = "simulation", madsim)))]
65    #[tokio::test(flavor = "current_thread", start_paused = true)]
66    async fn test_dst_sleep_advances_paused_clock() {
67        let start = time::Instant::now();
68        time::sleep(time::Duration::from_mins(1)).await;
69        assert!(start.elapsed() >= time::Duration::from_mins(1));
70    }
71
72    #[cfg(all(feature = "simulation", madsim))]
73    #[madsim::test]
74    async fn test_dst_timeout_fires_in_virtual_time() {
75        let result = time::timeout(
76            time::Duration::from_millis(10),
77            std::future::pending::<()>(),
78        )
79        .await;
80        assert!(
81            result.is_err(),
82            "timeout should fire on a never-completing future"
83        );
84    }
85}
nautilus_network/dst.rs

nautilus_network/
dst.rs
