algocline_core/execution/
cancel.rs

1//! Cancellation and failure types for the `ExecutionService` layer.
2
3use serde::{Deserialize, Serialize};
4
5use super::state::ExecutionState;
6
7/// Reason supplied to [`crate::execution::ExecutionService::cancel`].
8///
9/// `requested_at` is a Unix timestamp in milliseconds.
10#[derive(Debug, Clone, Serialize, Deserialize)]
11pub struct CancelReason {
12    /// Categorized cause of the cancellation.
13    pub code: CancelCode,
14    /// Optional human-readable detail string.
15    pub detail: Option<String>,
16    /// Unix timestamp (milliseconds) when the cancellation was requested.
17    pub requested_at: i64,
18}
19
20/// Categorized cause of a cancellation.
21///
22/// This is a **closed** enum — `#[non_exhaustive]` is intentionally absent so that
23/// exhaustive `match` is enforced on consumers (design-v1.md §2).
24///
25/// No forceful kill variants (e.g., `Aborted`, `Killed`, `ForcedExit`) are included;
26/// all cancellation in this design is cooperative (crux: Cooperative cancellation
27/// 4-checkpoint).
28#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
29#[serde(rename_all = "snake_case")]
30pub enum CancelCode {
31    /// Requested explicitly by a human or calling client.
32    User,
33    /// A deadline or time budget was exceeded.
34    Timeout,
35    /// The parent context (e.g., the service instance) was dropped.
36    ParentDropped,
37    /// The process is shutting down gracefully.
38    SystemShutdown,
39    /// Internal engine policy triggered cancellation.
40    Internal,
41}
42
43/// Information recorded when a session transitions to `Cancelled`.
44///
45/// `state_before` is boxed to avoid a recursive type without indirection.
46/// `observed_at` is a Unix timestamp in milliseconds.
47#[derive(Debug, Clone, Serialize, Deserialize)]
48pub struct CancelInfo {
49    /// The reason that triggered cancellation.
50    pub reason: CancelReason,
51    /// Unix timestamp (milliseconds) when the cancellation was observed by the engine.
52    pub observed_at: i64,
53    /// A snapshot of the [`ExecutionState`] immediately before cancellation was applied.
54    #[serde(rename = "state_before")]
55    pub state_before: Box<ExecutionState>,
56}
57
58/// Information recorded when a session transitions to `Failed`.
59///
60/// `occurred_at` is a Unix timestamp in milliseconds.
61#[derive(Debug, Clone, Serialize, Deserialize)]
62pub struct FailureInfo {
63    /// Human-readable error message.
64    pub message: String,
65    /// Categorized kind of failure.
66    pub kind: FailureKind,
67    /// Unix timestamp (milliseconds) when the failure was recorded.
68    pub occurred_at: i64,
69}
70
71/// Categorized kind of failure.
72///
73/// Closed enum — `#[non_exhaustive]` intentionally absent.
74#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
75#[serde(rename_all = "snake_case")]
76pub enum FailureKind {
77    /// A Lua runtime error occurred.
78    LuaError,
79    /// An internal engine error occurred.
80    EngineError,
81    /// A timeout was exceeded during execution.
82    Timeout,
83    /// Any other failure not covered by the above variants.
84    Other,
85}
algocline_core/execution/cancel.rs

algocline_core/execution/
cancel.rs
