nautilus_live/book/
mod.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//! Shared order book recovery state, sequence decisions, and snapshot coordination.
17//!
18//! - [`recovery`] owns recovery episodes, retry budgets, cancellation, and terminal failure state.
19//! - [`snapshot`] coordinates subscription write confirmation with snapshot acceptance and deadlines.
20//! - [`BookSequenceOutcome`] and [`BookSyncSignalKind`] describe validation decisions and monitoring
21//!   signals without carrying venue-specific sequence fields or channel types.
22//!
23//! # Recovery Lifecycle
24//!
25//! The adapter validates incoming book frames and claims recovery through
26//! [`BookRecoveryState`](recovery::BookRecoveryState). The recovery runner requests replacement
27//! subscriptions through an adapter-supplied operation. A confirmed write opens the snapshot gate;
28//! only an accepted fresh snapshot completes recovery. The adapter reports terminal failure through
29//! the same recovery state, preventing obsolete work from failing a newer subscription.
30//!
31//! # Adapters
32//!
33//! Adapters retain sequence rules, cached levels, socket routing, wire commands, acknowledgement
34//! correlation, and error classification. They keep state transitions under their existing lock or
35//! owning task and retain an active recovery across reconnects so its retry budget is not reset.
36//!
37//! A monitoring signal does not itself start recovery; the adapter decides how to respond.
38
39pub mod recovery;
40pub mod snapshot;
41
42use nautilus_common::live::dst::time::Duration;
43
44/// Default wait for an initial, post-reconnect, or recovery order book snapshot, in seconds.
45///
46/// Adapters use this as their `book_snapshot_timeout_secs` default; the config
47/// value remains tunable per deployment.
48pub const DEFAULT_BOOK_SNAPSHOT_TIMEOUT_SECS: u64 = 10;
49
50/// Decision from an adapter's book sequence validation.
51#[derive(Debug, Clone, Copy, PartialEq, Eq)]
52pub enum BookSequenceOutcome {
53    /// Process the book snapshot or incremental update.
54    Accept,
55    /// Discard the frame without starting another recovery.
56    Suppress,
57    /// Discard the frame and request a fresh snapshot.
58    Recover,
59}
60
61/// Condition reported while monitoring book synchronization.
62#[derive(Debug, Clone, Copy, PartialEq, Eq)]
63pub enum BookSyncSignalKind {
64    /// No accepted book update arrived within the stale-feed threshold.
65    Stale { elapsed: Duration },
66    /// The expected book snapshot did not arrive before its deadline.
67    SnapshotMissing,
68}
69
70#[cfg(test)]
71mod tests {
72    use rstest::rstest;
73
74    use super::*;
75
76    #[rstest]
77    fn default_book_snapshot_timeout_is_ten_seconds() {
78        assert_eq!(DEFAULT_BOOK_SNAPSHOT_TIMEOUT_SECS, 10);
79    }
80}
nautilus_live/book/mod.rs

nautilus_live/book/
mod.rs
