Skip to main content

nautilus_testkit/
events.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//! Collection utilities for the data events a client emits onto the live runner channel.
17
18use std::time::Duration;
19
20use nautilus_common::messages::DataEvent;
21use nautilus_core::UUID4;
22
23/// Collects the data events received on `rx` within `timeout`.
24///
25/// While the live runner's thread-local sender keeps the channel open, this waits out the full
26/// window and suits absence checks. Prefer [`collect_data_events_until_response`] whenever the
27/// events end with a correlated response.
28pub async fn drain_data_events(
29    rx: &mut tokio::sync::mpsc::UnboundedReceiver<DataEvent>,
30    timeout: Duration,
31) -> Vec<DataEvent> {
32    let mut events = Vec::new();
33    let deadline = tokio::time::Instant::now() + timeout;
34    while let Ok(Some(event)) = tokio::time::timeout_at(deadline, rx.recv()).await {
35        events.push(event);
36    }
37    events
38}
39
40/// Collects the data events received on `rx` up to and including the response correlated with
41/// `request_id`, then drains any further events available without waiting.
42///
43/// A response envelope ends the collection only once it is completed. `timeout` bounds only the
44/// wait through the correlated response, so a passing run returns when that response arrives
45/// instead of waiting out the window.
46///
47/// # Panics
48///
49/// Panics if the channel closes before the correlated response arrives, or if that response does
50/// not arrive within `timeout`.
51pub async fn collect_data_events_until_response(
52    rx: &mut tokio::sync::mpsc::UnboundedReceiver<DataEvent>,
53    request_id: UUID4,
54    timeout: Duration,
55) -> Vec<DataEvent> {
56    let mut events = Vec::new();
57    tokio::time::timeout(timeout, async {
58        loop {
59            let event = rx.recv().await.expect("data event channel closed");
60
61            let is_correlated_response = match &event {
62                DataEvent::Response(response) => response.correlation_id() == &request_id,
63                DataEvent::ResponseEnvelope(envelope) => {
64                    envelope.completed() && envelope.correlation_id() == &request_id
65                }
66                _ => false,
67            };
68
69            events.push(event);
70
71            if is_correlated_response {
72                break;
73            }
74        }
75    })
76    .await
77    .unwrap_or_else(|_| panic!("timed out waiting for data response {request_id}"));
78
79    while let Ok(event) = rx.try_recv() {
80        events.push(event);
81    }
82
83    events
84}
85
86#[cfg(test)]
87mod tests {
88    use nautilus_common::messages::{
89        DataResponse,
90        data::{DataResponseEnvelope, InstrumentsResponse},
91    };
92    use nautilus_core::UnixNanos;
93    use nautilus_model::{
94        identifiers::{ClientId, Venue},
95        instruments::{InstrumentAny, stubs::equity_aapl_itch},
96        stubs::TestDefault,
97    };
98    use rstest::rstest;
99
100    use super::*;
101
102    fn instruments_response(correlation_id: UUID4) -> DataEvent {
103        DataEvent::Response(instruments(correlation_id))
104    }
105
106    fn instruments_envelope(correlation_id: UUID4, completed: bool) -> DataEvent {
107        DataEvent::ResponseEnvelope(DataResponseEnvelope::new(
108            instruments(correlation_id),
109            completed,
110            None,
111        ))
112    }
113
114    fn instruments(correlation_id: UUID4) -> DataResponse {
115        DataResponse::Instruments(InstrumentsResponse::new(
116            correlation_id,
117            ClientId::test_default(),
118            Venue::test_default(),
119            Vec::new(),
120            None,
121            None,
122            UnixNanos::default(),
123            None,
124        ))
125    }
126
127    fn correlation_ids(events: &[DataEvent]) -> Vec<Option<UUID4>> {
128        events
129            .iter()
130            .map(|event| match event {
131                DataEvent::Response(response) => Some(*response.correlation_id()),
132                _ => None,
133            })
134            .collect()
135    }
136
137    #[rstest]
138    #[case(0)]
139    #[case(3)]
140    #[tokio::test(start_paused = true)]
141    async fn test_drain_data_events_collects_events_queued_before_deadline(#[case] count: usize) {
142        let (tx, mut rx) = tokio::sync::mpsc::unbounded_channel();
143        let request_ids: Vec<UUID4> = (0..count).map(|_| UUID4::new()).collect();
144        for request_id in &request_ids {
145            tx.send(instruments_response(*request_id)).unwrap();
146        }
147
148        let events = drain_data_events(&mut rx, Duration::from_millis(50)).await;
149
150        assert_eq!(
151            correlation_ids(&events),
152            request_ids.iter().copied().map(Some).collect::<Vec<_>>()
153        );
154    }
155
156    #[rstest]
157    #[tokio::test(start_paused = true)]
158    async fn test_drain_data_events_stops_at_the_absolute_deadline() {
159        let (tx, mut rx) = tokio::sync::mpsc::unbounded_channel();
160        let first_id = UUID4::new();
161        let second_id = UUID4::new();
162        let late_id = UUID4::new();
163
164        // The 40ms and 80ms sends land inside the 100ms window, the 160ms send past it
165        tokio::spawn(async move {
166            tokio::time::sleep(Duration::from_millis(40)).await;
167            tx.send(instruments_response(first_id)).unwrap();
168            tokio::time::sleep(Duration::from_millis(40)).await;
169            tx.send(instruments_response(second_id)).unwrap();
170            tokio::time::sleep(Duration::from_millis(80)).await;
171            tx.send(instruments_response(late_id)).unwrap();
172        });
173
174        let start = tokio::time::Instant::now();
175        let events = drain_data_events(&mut rx, Duration::from_millis(100)).await;
176
177        assert_eq!(
178            correlation_ids(&events),
179            vec![Some(first_id), Some(second_id)]
180        );
181        assert_eq!(start.elapsed(), Duration::from_millis(100));
182    }
183
184    #[rstest]
185    #[tokio::test(start_paused = true)]
186    async fn test_drain_data_events_returns_when_channel_closes() {
187        let (tx, mut rx) = tokio::sync::mpsc::unbounded_channel();
188        let request_id = UUID4::new();
189        tx.send(instruments_response(request_id)).unwrap();
190        drop(tx);
191
192        let start = tokio::time::Instant::now();
193        let events = drain_data_events(&mut rx, Duration::from_secs(5)).await;
194
195        assert_eq!(correlation_ids(&events), vec![Some(request_id)]);
196        assert_eq!(start.elapsed(), Duration::ZERO);
197    }
198
199    #[rstest]
200    #[tokio::test(start_paused = true)]
201    async fn test_collect_data_events_until_response_returns_at_correlated_response() {
202        let (tx, mut rx) = tokio::sync::mpsc::unbounded_channel();
203        let other_id = UUID4::new();
204        let request_id = UUID4::new();
205        let trailing_id = UUID4::new();
206        tx.send(DataEvent::Data(
207            InstrumentAny::Equity(equity_aapl_itch()).into(),
208        ))
209        .unwrap();
210        tx.send(instruments_response(other_id)).unwrap();
211        tx.send(instruments_response(request_id)).unwrap();
212        tx.send(instruments_response(trailing_id)).unwrap();
213
214        let start = tokio::time::Instant::now();
215        let events =
216            collect_data_events_until_response(&mut rx, request_id, Duration::from_secs(5)).await;
217
218        assert_eq!(
219            correlation_ids(&events),
220            vec![None, Some(other_id), Some(request_id), Some(trailing_id)]
221        );
222        assert_eq!(start.elapsed(), Duration::ZERO);
223    }
224
225    #[rstest]
226    #[tokio::test(start_paused = true)]
227    async fn test_collect_data_events_until_response_returns_at_completed_envelope() {
228        let (tx, mut rx) = tokio::sync::mpsc::unbounded_channel();
229        let other_id = UUID4::new();
230        let request_id = UUID4::new();
231        tx.send(instruments_envelope(other_id, true)).unwrap();
232        tx.send(instruments_envelope(request_id, false)).unwrap();
233
234        tokio::spawn(async move {
235            tokio::time::sleep(Duration::from_millis(40)).await;
236            tx.send(instruments_envelope(request_id, true)).unwrap();
237        });
238
239        let start = tokio::time::Instant::now();
240        let events =
241            collect_data_events_until_response(&mut rx, request_id, Duration::from_secs(5)).await;
242        let envelopes: Vec<(UUID4, bool)> = events
243            .iter()
244            .filter_map(|event| match event {
245                DataEvent::ResponseEnvelope(envelope) => {
246                    Some((*envelope.correlation_id(), envelope.completed()))
247                }
248                _ => None,
249            })
250            .collect();
251
252        assert_eq!(
253            envelopes,
254            vec![(other_id, true), (request_id, false), (request_id, true)]
255        );
256        assert_eq!(start.elapsed(), Duration::from_millis(40));
257    }
258
259    #[rstest]
260    #[tokio::test(start_paused = true)]
261    #[should_panic(expected = "timed out waiting for data response")]
262    async fn test_collect_data_events_until_response_panics_without_correlated_response() {
263        let (tx, mut rx) = tokio::sync::mpsc::unbounded_channel();
264        tx.send(instruments_response(UUID4::new())).unwrap();
265
266        collect_data_events_until_response(&mut rx, UUID4::new(), Duration::from_millis(50)).await;
267    }
268
269    #[rstest]
270    #[tokio::test]
271    #[should_panic(expected = "data event channel closed")]
272    async fn test_collect_data_events_until_response_panics_when_channel_closes() {
273        let (tx, mut rx) = tokio::sync::mpsc::unbounded_channel::<DataEvent>();
274        drop(tx);
275
276        collect_data_events_until_response(&mut rx, UUID4::new(), Duration::from_secs(5)).await;
277    }
278}