nautilus_live/execution/
failure.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 classification of order command failures for live execution.
17
18/// Classifies why a state-changing order command failed, by the evidence available.
19///
20/// Adapters keep their own error types and map each submit, modify, or cancel failure to one
21/// variant, including the batch and list forms, so the same wire condition classifies identically
22/// across venues. A definitive venue acceptance or update is not a failure and carries no variant.
23///
24/// This axis is independent of retryability. Retryability answers whether to send the request
25/// again; this answers whether the venue may already have acted on the first attempt. An error can
26/// be both, either, or neither.
27#[derive(Debug, Clone, PartialEq, Eq)]
28pub enum CommandFailure {
29    /// A deterministic local failure proves the command was never transmitted.
30    ///
31    /// A terminal rejection event is valid for this evidence.
32    NotSent(String),
33    /// The venue outcome is undefined; the command may still have been applied.
34    ///
35    /// A terminal event is never valid for this evidence. Leave the command in flight for a
36    /// stream update, query, poll, or reconciliation to resolve it either way.
37    Ambiguous(String),
38    /// The venue explicitly declared the command rejected.
39    ///
40    /// A terminal rejection event is valid for this evidence.
41    VenueRejected(String),
42}
43
44impl CommandFailure {
45    /// Creates a new [`CommandFailure::NotSent`] with the given `reason`.
46    #[must_use]
47    pub fn not_sent(reason: impl Into<String>) -> Self {
48        Self::NotSent(reason.into())
49    }
50
51    /// Creates a new [`CommandFailure::Ambiguous`] with the given `reason`.
52    #[must_use]
53    pub fn ambiguous(reason: impl Into<String>) -> Self {
54        Self::Ambiguous(reason.into())
55    }
56
57    /// Creates a new [`CommandFailure::VenueRejected`] with the given `reason`.
58    #[must_use]
59    pub fn venue_rejected(reason: impl Into<String>) -> Self {
60        Self::VenueRejected(reason.into())
61    }
62}
63
64#[cfg(test)]
65mod tests {
66    use rstest::rstest;
67
68    use super::CommandFailure;
69
70    #[rstest]
71    #[case(
72        CommandFailure::not_sent("Failed to build cancel params"),
73        CommandFailure::NotSent("Failed to build cancel params".to_string())
74    )]
75    #[case(
76        CommandFailure::ambiguous("connection closed"),
77        CommandFailure::Ambiguous("connection closed".to_string())
78    )]
79    #[case(
80        CommandFailure::venue_rejected("EOrder:Unknown order"),
81        CommandFailure::VenueRejected("EOrder:Unknown order".to_string())
82    )]
83    fn test_constructor_variant_and_reason(
84        #[case] failure: CommandFailure,
85        #[case] expected: CommandFailure,
86    ) {
87        assert_eq!(failure, expected);
88    }
89}
nautilus_live/execution/failure.rs

nautilus_live/execution/
failure.rs
