Skip to main content

oxide_batch_core/
flow.rs

1//! Durable flow identities, transition targets, and start controls.
2//!
3//! Every value here is written to metadata, read back on restart, or
4//! hashed into a definition fingerprint. The graph that arranges them and
5//! the compiler that validates it live above this crate.
6
7use std::num::NonZeroU32;
8
9use crate::{DefinitionError, DefinitionTokenKind, definition_token, validate_token};
10
11/// The maximum number of durable local partitions in one partitioned step.
12pub const MAX_PARTITIONS: u16 = 1_024;
13definition_token!(
14    NodeId,
15    DefinitionTokenKind::Node,
16    "A stable logical identifier for one flow-graph node.
17
18Logical identity survives display-name changes. Runtime and database
19identifiers are never node identifiers."
20);
21/// The maximum number of step executions one logical step may start.
22///
23/// The default is `u32::MAX`: an effectively unrestricted step that remains a
24/// finite typed value rather than an absent bound.
25#[derive(Clone, Copy, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
26pub struct StartLimit(NonZeroU32);
27
28impl StartLimit {
29    /// The unrestricted default.
30    pub const UNRESTRICTED: Self = Self(NonZeroU32::MAX);
31
32    /// Constructs a nonzero start limit.
33    ///
34    /// # Errors
35    ///
36    /// Returns [`DefinitionError::ZeroStartLimit`] for zero, because a step
37    /// that can never start is a definition mistake rather than a policy.
38    pub fn new(value: u32) -> Result<Self, DefinitionError> {
39        NonZeroU32::new(value)
40            .map(Self)
41            .ok_or(DefinitionError::ZeroStartLimit)
42    }
43
44    /// Returns the limit.
45    #[must_use]
46    pub const fn get(self) -> u32 {
47        self.0.get()
48    }
49}
50
51impl Default for StartLimit {
52    fn default() -> Self {
53        Self::UNRESTRICTED
54    }
55}
56
57/// Whether a job or logical step may be entered by a later execution attempt.
58///
59/// This M7 execution-definition policy is distinct from
60/// `RestartabilityDeclaration`, which describes whether component state can be
61/// reconstructed. The default preserves every pre-M7 definition's restart
62/// behavior and manifest identity.
63#[derive(Clone, Copy, Debug, Default, Eq, Hash, Ord, PartialEq, PartialOrd)]
64#[non_exhaustive]
65pub enum RestartPolicy {
66    /// Later failed/stopped execution attempts may re-enter this definition.
67    #[default]
68    Restartable,
69    /// A later execution attempt must fail closed before re-entering this definition.
70    NotRestartable,
71}
72
73impl RestartPolicy {
74    /// Returns whether a later execution attempt may re-enter this definition.
75    #[must_use]
76    pub const fn is_restartable(self) -> bool {
77        matches!(self, Self::Restartable)
78    }
79}
80
81/// Restart-relevant start controls for one logical step.
82#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
83pub struct StartControls {
84    start_limit: StartLimit,
85    allow_start_if_complete: bool,
86    restart_policy: RestartPolicy,
87}
88
89impl StartControls {
90    /// Constructs explicit start controls.
91    #[must_use]
92    pub const fn new(start_limit: StartLimit, allow_start_if_complete: bool) -> Self {
93        Self {
94            start_limit,
95            allow_start_if_complete,
96            restart_policy: RestartPolicy::Restartable,
97        }
98    }
99
100    /// Applies the explicit execution-definition restart policy.
101    #[must_use]
102    pub const fn with_restart_policy(mut self, restart_policy: RestartPolicy) -> Self {
103        self.restart_policy = restart_policy;
104        self
105    }
106
107    /// Returns the maximum number of starts for one job instance.
108    #[must_use]
109    pub const fn start_limit(&self) -> StartLimit {
110        self.start_limit
111    }
112
113    /// Returns whether a restart path reruns an already completed step.
114    #[must_use]
115    pub const fn allow_start_if_complete(&self) -> bool {
116        self.allow_start_if_complete
117    }
118
119    /// Returns the execution-definition restart policy for this logical step.
120    #[must_use]
121    pub const fn restart_policy(&self) -> RestartPolicy {
122        self.restart_policy
123    }
124}
125
126/// A node that ends the job without starting further work.
127#[derive(Clone, Copy, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
128#[non_exhaustive]
129pub enum TerminalKind {
130    /// The job completes.
131    Complete,
132    /// The job fails.
133    Fail,
134    /// The job stops and remains restartable.
135    Stop,
136}
137
138impl TerminalKind {
139    /// Returns the stable manifest and telemetry name.
140    #[must_use]
141    pub const fn as_str(self) -> &'static str {
142        match self {
143            Self::Complete => "complete",
144            Self::Fail => "fail",
145            Self::Stop => "stop",
146        }
147    }
148}
149
150/// The destination one transition selects.
151#[derive(Clone, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
152pub enum FlowTarget {
153    /// Another graph node starts next.
154    Node(NodeId),
155    /// The job ends at a terminal.
156    Terminal(TerminalKind),
157}
158
159impl FlowTarget {
160    /// Returns the deterministic ordering key for canonical output.
161    #[must_use]
162    pub fn sort_key(&self) -> (u8, &str) {
163        match self {
164            Self::Node(id) => (0, id.as_str()),
165            Self::Terminal(kind) => (1, kind.as_str()),
166        }
167    }
168}