Skip to main content

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    /// After `OrderSubmitted`, submit emits `OrderRejected`; modify and cancel emit their
32    /// corresponding denied event.
33    NotSent(String),
34    /// The venue outcome is undefined; the command may still have been applied.
35    ///
36    /// A terminal event is never valid for this evidence. Leave the command in flight for a
37    /// stream update, query, poll, or reconciliation to resolve it either way.
38    Ambiguous(String),
39    /// The venue explicitly declared the command rejected.
40    ///
41    /// Emit the corresponding rejected event. Modify and cancel preserve the working order.
42    VenueRejected(String),
43}
44
45impl CommandFailure {
46    /// Creates a new [`CommandFailure::NotSent`] with the given `reason`.
47    #[must_use]
48    pub fn not_sent(reason: impl Into<String>) -> Self {
49        Self::NotSent(reason.into())
50    }
51
52    /// Creates a new [`CommandFailure::Ambiguous`] with the given `reason`.
53    #[must_use]
54    pub fn ambiguous(reason: impl Into<String>) -> Self {
55        Self::Ambiguous(reason.into())
56    }
57
58    /// Creates a new [`CommandFailure::VenueRejected`] with the given `reason`.
59    #[must_use]
60    pub fn venue_rejected(reason: impl Into<String>) -> Self {
61        Self::VenueRejected(reason.into())
62    }
63}
64
65#[cfg(test)]
66mod tests {
67    use rstest::rstest;
68
69    use super::CommandFailure;
70
71    #[rstest]
72    #[case(
73        CommandFailure::not_sent("Failed to build cancel params"),
74        CommandFailure::NotSent("Failed to build cancel params".to_string())
75    )]
76    #[case(
77        CommandFailure::ambiguous("connection closed"),
78        CommandFailure::Ambiguous("connection closed".to_string())
79    )]
80    #[case(
81        CommandFailure::venue_rejected("EOrder:Unknown order"),
82        CommandFailure::VenueRejected("EOrder:Unknown order".to_string())
83    )]
84    fn test_constructor_variant_and_reason(
85        #[case] failure: CommandFailure,
86        #[case] expected: CommandFailure,
87    ) {
88        assert_eq!(failure, expected);
89    }
90}