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}