1#![forbid(unsafe_code)]
46
47mod advanced;
48mod custom_leaf;
49mod late_binding;
50mod nested_job;
51mod repeat;
52
53pub use custom_leaf::{CustomLeafKind, CustomLeafNode};
54
55pub use late_binding::{
56 LateBindingDefinitionError, LateBoundInput, LateBoundSource, MAX_LATE_BOUND_INPUTS,
57 MAX_SCOPED_COMPONENTS, ScopeFactoryKind, ScopeFrameworkSource, ScopeKind, ScopeResolverKind,
58 ScopedComponentDefinition, ScopedComponentId,
59};
60
61pub use nested_job::{
62 FrameworkParameterSource, MAX_NESTED_JOB_PARAMETERS, MAX_SELECTOR_PATH_BYTES,
63 MAX_SELECTOR_PATH_SEGMENTS, MissingParameterPolicy, NestedJobNode, NestedJobParameterMapping,
64 NestedJobParameterSource, ParameterCoercion, SelectorPath,
65};
66pub use oxide_batch_core::RepeatId;
67pub use repeat::{
68 RepeatDefinition, RepeatDefinitionError, RepeatInterceptorDefinition, RepeatInterceptorId,
69 RepeatInterceptorKind, RepeatPolicyConfiguration, RepeatPolicyDefinition, RepeatPolicyKind,
70 RepeatStateSchema,
71};
72
73use std::collections::{BTreeMap, BTreeSet};
74use std::error::Error;
75use std::fmt;
76use std::num::NonZeroU32;
77
78use serde_json::{Value, json};
79
80use oxide_batch_core::{
81 ChunkComponentRevisions, ChunkSize, ComponentRevision, DefinitionError, DefinitionIdentity,
82 DefinitionRevision, DefinitionTokenKind, ExitCode, FaultPolicy, FlowTarget, InFlightPolicy,
83 JobName, MAX_NODES, MAX_PARTITIONS, MAX_TRANSITIONS, NodeId, ParameterIncrementerIdentity,
84 ParameterName, RestartPolicy, StartControls, StepName, TerminalKind, definition_token,
85 validate_token,
86};
87
88pub const MAX_OUTGOING_TRANSITIONS: usize = 64;
90pub const MAX_PATTERN_BYTES: usize = 64;
92pub const MAX_SPLIT_BRANCHES: usize = 8;
94pub const MAX_BRANCH_STEPS: usize = 8;
96pub const MAX_PARTITION_WORKERS: u8 = 64;
98pub const MAX_FLOW_COMPOSITION_DEPTH: usize = 8;
100
101#[derive(Clone, Copy, Debug, Default, Eq, Hash, Ord, PartialEq, PartialOrd)]
103#[non_exhaustive]
104pub enum LocalFailurePolicy {
105 #[default]
107 CancelSiblings,
108 DrainSiblings,
110}
111
112impl LocalFailurePolicy {
113 const fn as_str(self) -> &'static str {
114 match self {
115 Self::CancelSiblings => "cancel_siblings",
116 Self::DrainSiblings => "drain_siblings",
117 }
118 }
119}
120
121#[derive(Clone, Copy, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
123pub struct SplitBudget {
124 max_parallel_branches: u8,
125 repository_pool_size: u32,
126}
127
128impl SplitBudget {
129 pub fn new(max_parallel_branches: u8, repository_pool_size: u32) -> Result<Self, PlanError> {
136 if max_parallel_branches == 0 || usize::from(max_parallel_branches) > MAX_SPLIT_BRANCHES {
137 return Err(PlanError::InvalidParallelBranchBudget {
138 max: MAX_SPLIT_BRANCHES,
139 });
140 }
141 let required = u32::from(max_parallel_branches).saturating_add(1);
142 if repository_pool_size < required {
143 return Err(PlanError::InsufficientPoolCapacity {
144 required,
145 configured: repository_pool_size,
146 });
147 }
148 Ok(Self {
149 max_parallel_branches,
150 repository_pool_size,
151 })
152 }
153
154 #[must_use]
156 pub const fn max_parallel_branches(self) -> u8 {
157 self.max_parallel_branches
158 }
159
160 #[must_use]
162 pub const fn repository_pool_size(self) -> u32 {
163 self.repository_pool_size
164 }
165}
166
167impl Default for SplitBudget {
168 fn default() -> Self {
169 Self {
170 max_parallel_branches: 1,
171 repository_pool_size: 2,
172 }
173 }
174}
175
176#[derive(Clone, Copy, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
178pub struct PartitionBudget {
179 max_partition_workers: u8,
180 repository_pool_size: u32,
181}
182
183impl PartitionBudget {
184 pub fn new(max_partition_workers: u8, repository_pool_size: u32) -> Result<Self, PlanError> {
191 if !(1..=MAX_PARTITION_WORKERS).contains(&max_partition_workers) {
192 return Err(PlanError::InvalidPartitionWorkerBudget {
193 max: MAX_PARTITION_WORKERS,
194 });
195 }
196 let required = u32::from(max_partition_workers).saturating_add(1);
197 if repository_pool_size < required {
198 return Err(PlanError::InsufficientPoolCapacity {
199 required,
200 configured: repository_pool_size,
201 });
202 }
203 Ok(Self {
204 max_partition_workers,
205 repository_pool_size,
206 })
207 }
208
209 #[must_use]
211 pub const fn max_partition_workers(self) -> u8 {
212 self.max_partition_workers
213 }
214
215 #[must_use]
217 pub const fn repository_pool_size(self) -> u32 {
218 self.repository_pool_size
219 }
220}
221
222impl Default for PartitionBudget {
223 fn default() -> Self {
224 Self {
225 max_partition_workers: 4,
226 repository_pool_size: 5,
227 }
228 }
229}
230
231definition_token!(
232 DeciderRevision,
233 DefinitionTokenKind::Decider,
234 "An application-owned revision token for one deterministic decider."
235);
236
237#[derive(Clone, Copy, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
239pub struct DecisionInputVersion(NonZeroU32);
240
241impl DecisionInputVersion {
242 pub fn new(value: u32) -> Result<Self, PlanError> {
248 NonZeroU32::new(value)
249 .map(Self)
250 .ok_or(PlanError::ZeroDecisionInputVersion)
251 }
252
253 #[must_use]
255 pub const fn get(self) -> u32 {
256 self.0.get()
257 }
258}
259
260#[derive(Clone, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
269pub struct ExitPattern(String);
270
271impl ExitPattern {
272 pub fn new(value: impl Into<String>) -> Result<Self, PlanError> {
280 let value = value.into();
281 if value.is_empty()
282 || value.len() > MAX_PATTERN_BYTES
283 || value.trim() != value
284 || value.chars().any(char::is_control)
285 {
286 return Err(PlanError::InvalidPattern {
287 max_bytes: MAX_PATTERN_BYTES,
288 });
289 }
290 Ok(Self(value))
291 }
292
293 #[must_use]
295 pub fn as_str(&self) -> &str {
296 &self.0
297 }
298
299 #[must_use]
301 pub fn matches(&self, code: &ExitCode) -> bool {
302 let pattern: Vec<char> = self.0.chars().collect();
303 let value: Vec<char> = code.as_str().chars().collect();
304 matches_from(&pattern, &value)
305 }
306
307 #[must_use]
311 pub fn specificity(&self) -> PatternSpecificity {
312 let wildcards = self
313 .0
314 .chars()
315 .filter(|character| matches!(character, '*' | '?'))
316 .count();
317 let literals = self.0.chars().count() - wildcards;
318 PatternSpecificity {
319 literals,
320 wildcards,
321 bytes: self.0.len(),
322 }
323 }
324
325 #[must_use]
327 pub fn intersects(&self, other: &Self) -> bool {
328 let left: Vec<char> = self.0.chars().collect();
329 let right: Vec<char> = other.0.chars().collect();
330 let mut memo = vec![None; (left.len() + 1) * (right.len() + 1)];
331 intersects_from(&left, &right, 0, 0, &mut memo)
332 }
333}
334
335impl fmt::Display for ExitPattern {
336 fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
337 formatter.write_str(&self.0)
338 }
339}
340
341fn matches_from(pattern: &[char], value: &[char]) -> bool {
342 let mut pattern_index = 0_usize;
343 let mut value_index = 0_usize;
344 let mut star: Option<(usize, usize)> = None;
345 while value_index < value.len() {
346 match pattern.get(pattern_index) {
347 Some('*') => {
348 star = Some((pattern_index, value_index));
349 pattern_index += 1;
350 }
351 Some('?') => {
352 pattern_index += 1;
353 value_index += 1;
354 }
355 Some(literal) if *literal == value[value_index] => {
356 pattern_index += 1;
357 value_index += 1;
358 }
359 _ => match star {
360 Some((star_index, resume)) => {
361 pattern_index = star_index + 1;
362 value_index = resume + 1;
363 star = Some((star_index, resume + 1));
364 }
365 None => return false,
366 },
367 }
368 }
369 pattern[pattern_index..]
370 .iter()
371 .all(|character| *character == '*')
372}
373
374fn intersects_from(
375 left: &[char],
376 right: &[char],
377 left_index: usize,
378 right_index: usize,
379 memo: &mut [Option<bool>],
380) -> bool {
381 let key = left_index * (right.len() + 1) + right_index;
382 if let Some(cached) = memo[key] {
383 return cached;
384 }
385 let answer = match (left.get(left_index), right.get(right_index)) {
386 (None, None) => true,
387 (None, Some(_)) => right[right_index..].iter().all(|value| *value == '*'),
388 (Some(_), None) => left[left_index..].iter().all(|value| *value == '*'),
389 (Some('*'), _) => {
390 intersects_from(left, right, left_index + 1, right_index, memo)
391 || intersects_from(left, right, left_index, right_index + 1, memo)
392 }
393 (_, Some('*')) => {
394 intersects_from(left, right, left_index, right_index + 1, memo)
395 || intersects_from(left, right, left_index + 1, right_index, memo)
396 }
397 (Some(left_character), Some(right_character)) => {
398 (*left_character == '?' || *right_character == '?' || left_character == right_character)
399 && intersects_from(left, right, left_index + 1, right_index + 1, memo)
400 }
401 };
402 memo[key] = Some(answer);
403 answer
404}
405
406#[derive(Clone, Copy, Debug, Eq, PartialEq)]
411pub struct PatternSpecificity {
412 literals: usize,
413 wildcards: usize,
414 bytes: usize,
415}
416
417impl PatternSpecificity {
418 #[must_use]
420 pub const fn literals(self) -> usize {
421 self.literals
422 }
423
424 #[must_use]
426 pub const fn wildcards(self) -> usize {
427 self.wildcards
428 }
429
430 #[must_use]
432 pub const fn bytes(self) -> usize {
433 self.bytes
434 }
435}
436
437impl Ord for PatternSpecificity {
438 fn cmp(&self, other: &Self) -> std::cmp::Ordering {
439 self.literals
440 .cmp(&other.literals)
441 .then_with(|| other.wildcards.cmp(&self.wildcards))
442 .then_with(|| self.bytes.cmp(&other.bytes))
443 }
444}
445
446impl PartialOrd for PatternSpecificity {
447 fn partial_cmp(&self, other: &Self) -> Option<std::cmp::Ordering> {
448 Some(self.cmp(other))
449 }
450}
451
452#[derive(Clone, Debug, Eq, PartialEq)]
454#[non_exhaustive]
455pub enum StepComponents {
456 Tasklet(ComponentRevision),
458 Chunk {
460 size: ChunkSize,
462 revisions: Box<ChunkComponentRevisions>,
464 },
465}
466
467impl StepComponents {
468 fn kind_name(&self) -> &'static str {
469 match self {
470 Self::Tasklet(_) => "tasklet",
471 Self::Chunk { .. } => "chunk",
472 }
473 }
474
475 fn manifest_value(&self) -> Value {
476 match self {
477 Self::Tasklet(revision) => json!({
478 "component": revision.as_str(),
479 "delivery_mode": "best_effort",
480 "transaction_boundary": "tasklet_completion"
481 }),
482 Self::Chunk { size, revisions } => {
483 let mut chunk = chunk_declaration_manifest(revisions);
484 if let Some(members) = chunk.as_object_mut() {
485 members.insert("size".to_owned(), json!(size.get()));
486 members.insert(
487 "transaction_boundary".to_owned(),
488 Value::String("chunk".to_owned()),
489 );
490 }
491 chunk
492 }
493 }
494 }
495}
496
497#[derive(Clone, Debug, Eq, PartialEq)]
499pub struct StepNode {
500 id: NodeId,
501 step_name: StepName,
502 components: StepComponents,
503 start: StartControls,
504 fault: Option<FaultPolicy>,
505 listeners: Vec<ComponentRevision>,
506 repeat: Option<RepeatDefinition>,
507}
508
509impl StepNode {
510 #[must_use]
512 pub fn new(id: NodeId, step_name: StepName, components: StepComponents) -> Self {
513 Self {
514 id,
515 step_name,
516 components,
517 start: StartControls::default(),
518 fault: None,
519 listeners: Vec::new(),
520 repeat: None,
521 }
522 }
523
524 #[must_use]
526 pub const fn with_start_controls(mut self, start: StartControls) -> Self {
527 self.start = start;
528 self
529 }
530
531 #[must_use]
533 pub fn with_fault_policy(mut self, policy: FaultPolicy) -> Self {
534 self.fault = Some(policy);
535 self
536 }
537
538 #[must_use]
540 pub fn with_listener_revision(mut self, revision: ComponentRevision) -> Self {
541 self.listeners.push(revision);
542 self
543 }
544
545 #[must_use]
547 pub fn with_repeat_definition(mut self, repeat: RepeatDefinition) -> Self {
548 self.repeat = Some(repeat);
549 self
550 }
551
552 #[must_use]
554 pub const fn repeat_definition(&self) -> Option<&RepeatDefinition> {
555 self.repeat.as_ref()
556 }
557
558 #[must_use]
560 pub const fn id(&self) -> &NodeId {
561 &self.id
562 }
563
564 #[must_use]
566 pub const fn step_name(&self) -> &StepName {
567 &self.step_name
568 }
569
570 #[must_use]
572 pub const fn components(&self) -> &StepComponents {
573 &self.components
574 }
575
576 #[must_use]
578 pub const fn start_controls(&self) -> StartControls {
579 self.start
580 }
581
582 #[must_use]
584 pub const fn fault_policy(&self) -> Option<&FaultPolicy> {
585 self.fault.as_ref()
586 }
587
588 #[must_use]
590 pub fn listener_revisions(&self) -> &[ComponentRevision] {
591 &self.listeners
592 }
593
594 fn manifest_value(&self) -> Value {
595 let mut value = json!({
596 "id": self.id.as_str(),
597 "kind": "step",
598 "listeners": self
599 .listeners
600 .iter()
601 .map(|revision| Value::String(revision.as_str().to_owned()))
602 .collect::<Vec<_>>(),
603 "policy": self.fault.as_ref().map_or(Value::Null, fault_manifest_value),
604 "start": start_controls_manifest(self.start),
605 "step": {
606 "declaration": self.components.manifest_value(),
607 "kind": self.components.kind_name(),
608 "name": self.step_name.as_str()
609 }
610 });
611 if let Some(repeat) = &self.repeat
612 && let Some(object) = value.as_object_mut()
613 {
614 object.insert("repeat".to_owned(), repeat.manifest_value());
615 }
616 value
617 }
618}
619
620#[derive(Clone, Debug, Eq, PartialEq)]
625pub struct DecisionNode {
626 id: NodeId,
627 revision: DeciderRevision,
628 input_version: DecisionInputVersion,
629}
630
631impl DecisionNode {
632 #[must_use]
634 pub const fn new(
635 id: NodeId,
636 revision: DeciderRevision,
637 input_version: DecisionInputVersion,
638 ) -> Self {
639 Self {
640 id,
641 revision,
642 input_version,
643 }
644 }
645
646 #[must_use]
648 pub const fn id(&self) -> &NodeId {
649 &self.id
650 }
651
652 #[must_use]
654 pub const fn revision(&self) -> &DeciderRevision {
655 &self.revision
656 }
657
658 #[must_use]
660 pub const fn input_version(&self) -> DecisionInputVersion {
661 self.input_version
662 }
663
664 fn manifest_value(&self) -> Value {
665 json!({
666 "decision": {
667 "input_version": self.input_version.get(),
668 "revision": self.revision.as_str()
669 },
670 "id": self.id.as_str(),
671 "kind": "decision"
672 })
673 }
674}
675
676#[derive(Clone, Debug, Eq, PartialEq)]
678pub struct CompiledFlowScope {
679 entry: NodeId,
680 members: BTreeSet<NodeId>,
681}
682
683impl CompiledFlowScope {
684 pub(crate) fn new(entry: NodeId, members: BTreeSet<NodeId>) -> Self {
685 Self { entry, members }
686 }
687
688 #[must_use]
690 pub const fn entry(&self) -> &NodeId {
691 &self.entry
692 }
693
694 #[must_use]
696 pub fn contains(&self, node: &NodeId) -> bool {
697 self.members.contains(node)
698 }
699
700 #[must_use]
702 pub fn members(&self) -> impl ExactSizeIterator<Item = &NodeId> {
703 self.members.iter()
704 }
705}
706
707#[derive(Clone, Debug, Eq, PartialEq)]
709pub struct NestedFlow {
710 id: NodeId,
711 graph: Box<FlowGraph>,
712}
713
714impl NestedFlow {
715 #[must_use]
717 pub fn new(id: NodeId, graph: FlowGraph) -> Self {
718 Self {
719 id,
720 graph: Box::new(graph),
721 }
722 }
723
724 #[must_use]
726 pub const fn id(&self) -> &NodeId {
727 &self.id
728 }
729
730 #[must_use]
732 pub const fn graph(&self) -> &FlowGraph {
733 &self.graph
734 }
735}
736
737#[derive(Clone, Debug, Eq, PartialEq)]
739pub struct SplitBranch {
740 steps: Vec<StepNode>,
741 flow: Option<Box<FlowGraph>>,
742}
743
744impl SplitBranch {
745 #[must_use]
751 pub fn new(steps: Vec<StepNode>) -> Self {
752 Self { steps, flow: None }
753 }
754
755 #[must_use]
757 pub fn flow(graph: FlowGraph) -> Self {
758 Self {
759 steps: Vec::new(),
760 flow: Some(Box::new(graph)),
761 }
762 }
763
764 #[must_use]
769 pub fn steps(&self) -> &[StepNode] {
770 &self.steps
771 }
772
773 #[must_use]
775 pub fn flow_graph(&self) -> Option<&FlowGraph> {
776 self.flow.as_deref()
777 }
778
779 #[must_use]
784 pub fn id(&self) -> Option<&NodeId> {
785 self.steps.first().map(StepNode::id)
786 }
787
788 fn manifest_value(&self) -> Value {
789 Value::Array(self.steps.iter().map(StepNode::manifest_value).collect())
790 }
791}
792
793#[derive(Clone, Debug, Eq, PartialEq)]
795pub struct SplitNode {
796 id: NodeId,
797 branches: Vec<SplitBranch>,
798 join: NodeId,
799 budget: SplitBudget,
800 failure_policy: LocalFailurePolicy,
801}
802
803impl SplitNode {
804 #[must_use]
806 pub fn new(id: NodeId, branches: Vec<SplitBranch>, join: NodeId, budget: SplitBudget) -> Self {
807 Self {
808 id,
809 branches,
810 join,
811 budget,
812 failure_policy: LocalFailurePolicy::default(),
813 }
814 }
815
816 #[must_use]
818 pub const fn with_failure_policy(mut self, failure_policy: LocalFailurePolicy) -> Self {
819 self.failure_policy = failure_policy;
820 self
821 }
822
823 #[must_use]
825 pub const fn id(&self) -> &NodeId {
826 &self.id
827 }
828
829 #[must_use]
831 pub fn branches(&self) -> &[SplitBranch] {
832 &self.branches
833 }
834
835 #[must_use]
837 pub const fn join(&self) -> &NodeId {
838 &self.join
839 }
840
841 #[must_use]
843 pub const fn budget(&self) -> SplitBudget {
844 self.budget
845 }
846
847 #[must_use]
849 pub const fn failure_policy(&self) -> LocalFailurePolicy {
850 self.failure_policy
851 }
852
853 fn manifest_value(&self) -> Value {
859 json!({
860 "branches": self.branches.iter().map(SplitBranch::manifest_value).collect::<Vec<_>>(),
861 "failure_policy": self.failure_policy.as_str(),
862 "id": self.id.as_str(),
863 "join": self.join.as_str(),
864 "kind": "split"
865 })
866 }
867}
868
869#[derive(Clone, Debug, Eq, PartialEq)]
871pub struct JoinNode {
872 id: NodeId,
873}
874
875impl JoinNode {
876 #[must_use]
878 pub const fn new(id: NodeId) -> Self {
879 Self { id }
880 }
881
882 #[must_use]
884 pub const fn id(&self) -> &NodeId {
885 &self.id
886 }
887
888 fn manifest_value(&self) -> Value {
889 json!({
890 "id": self.id.as_str(),
891 "kind": "join"
892 })
893 }
894}
895
896#[derive(Clone, Copy, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
898pub struct PartitionCount(u16);
899
900impl PartitionCount {
901 pub fn new(value: u16) -> Result<Self, PlanError> {
907 if value == 0 || value > MAX_PARTITIONS {
908 return Err(PlanError::InvalidPartitionCount {
909 max: MAX_PARTITIONS,
910 });
911 }
912 Ok(Self(value))
913 }
914
915 #[must_use]
917 pub const fn get(self) -> u16 {
918 self.0
919 }
920}
921
922#[derive(Clone, Debug, Eq, PartialEq)]
924pub struct PartitionedStepNode {
925 id: NodeId,
926 step_name: StepName,
927 worker: StepNode,
928 partitioner: ComponentRevision,
929 aggregation: ComponentRevision,
930 partitions: PartitionCount,
931 budget: PartitionBudget,
932 failure_policy: LocalFailurePolicy,
933 start: StartControls,
934}
935
936impl PartitionedStepNode {
937 #[allow(clippy::too_many_arguments)]
939 #[must_use]
940 pub fn new(
941 id: NodeId,
942 step_name: StepName,
943 worker: StepNode,
944 partitioner: ComponentRevision,
945 aggregation: ComponentRevision,
946 partitions: PartitionCount,
947 budget: PartitionBudget,
948 ) -> Self {
949 Self {
950 id,
951 step_name,
952 worker,
953 partitioner,
954 aggregation,
955 partitions,
956 budget,
957 failure_policy: LocalFailurePolicy::default(),
958 start: StartControls::default(),
959 }
960 }
961
962 #[must_use]
964 pub const fn with_failure_policy(mut self, failure_policy: LocalFailurePolicy) -> Self {
965 self.failure_policy = failure_policy;
966 self
967 }
968
969 #[must_use]
971 pub const fn with_start_controls(mut self, start: StartControls) -> Self {
972 self.start = start;
973 self
974 }
975
976 #[must_use]
978 pub const fn id(&self) -> &NodeId {
979 &self.id
980 }
981
982 #[must_use]
984 pub const fn step_name(&self) -> &StepName {
985 &self.step_name
986 }
987
988 #[must_use]
990 pub const fn worker(&self) -> &StepNode {
991 &self.worker
992 }
993
994 #[must_use]
996 pub const fn partitioner(&self) -> &ComponentRevision {
997 &self.partitioner
998 }
999
1000 #[must_use]
1002 pub const fn aggregation(&self) -> &ComponentRevision {
1003 &self.aggregation
1004 }
1005
1006 #[must_use]
1008 pub const fn partition_count(&self) -> PartitionCount {
1009 self.partitions
1010 }
1011
1012 #[must_use]
1014 pub const fn budget(&self) -> PartitionBudget {
1015 self.budget
1016 }
1017
1018 #[must_use]
1020 pub const fn failure_policy(&self) -> LocalFailurePolicy {
1021 self.failure_policy
1022 }
1023
1024 #[must_use]
1026 pub const fn start_controls(&self) -> StartControls {
1027 self.start
1028 }
1029
1030 fn manifest_value(&self) -> Value {
1038 json!({
1039 "aggregation": self.aggregation.as_str(),
1040 "failure_policy": self.failure_policy.as_str(),
1041 "id": self.id.as_str(),
1042 "kind": "partitioned_step",
1043 "partition_count": self.partitions.get(),
1044 "partitioner": self.partitioner.as_str(),
1045 "start": start_controls_manifest(self.start),
1046 "step_name": self.step_name.as_str(),
1047 "worker": self.worker.manifest_value()
1048 })
1049 }
1050}
1051
1052#[derive(Clone, Debug, Eq, PartialEq)]
1054#[non_exhaustive]
1055pub enum FlowNode {
1056 Step(Box<StepNode>),
1058 Decision(DecisionNode),
1060 NestedJob(Box<NestedJobNode>),
1062 CustomLeaf(Box<CustomLeafNode>),
1064 Split(Box<SplitNode>),
1066 Join(JoinNode),
1068 PartitionedStep(Box<PartitionedStepNode>),
1070}
1071
1072impl FlowNode {
1073 fn has_nonrestartable_step(&self) -> bool {
1074 match self {
1075 Self::Step(step) => {
1076 step.start_controls().restart_policy() == RestartPolicy::NotRestartable
1077 }
1078 Self::CustomLeaf(custom) => {
1079 custom.start_controls().restart_policy() == RestartPolicy::NotRestartable
1080 }
1081 Self::PartitionedStep(partitioned) => {
1082 partitioned.start_controls().restart_policy() == RestartPolicy::NotRestartable
1083 || partitioned.worker().start_controls().restart_policy()
1084 == RestartPolicy::NotRestartable
1085 }
1086 Self::Split(split) => {
1087 split
1088 .branches()
1089 .iter()
1090 .flat_map(SplitBranch::steps)
1091 .any(|step| {
1092 step.start_controls().restart_policy() == RestartPolicy::NotRestartable
1093 })
1094 }
1095 _ => false,
1096 }
1097 }
1098
1099 fn has_repeat_definition(&self) -> bool {
1100 match self {
1101 Self::Step(step) => step.repeat_definition().is_some(),
1102 Self::PartitionedStep(partitioned) => {
1103 partitioned.worker().repeat_definition().is_some()
1104 }
1105 Self::Split(split) => split
1106 .branches()
1107 .iter()
1108 .flat_map(SplitBranch::steps)
1109 .any(|step| step.repeat_definition().is_some()),
1110 _ => false,
1111 }
1112 }
1113
1114 #[must_use]
1116 pub fn step(node: StepNode) -> Self {
1117 Self::Step(Box::new(node))
1118 }
1119
1120 #[must_use]
1122 pub const fn decision(node: DecisionNode) -> Self {
1123 Self::Decision(node)
1124 }
1125
1126 #[must_use]
1128 pub fn nested_job(node: NestedJobNode) -> Self {
1129 Self::NestedJob(Box::new(node))
1130 }
1131
1132 #[must_use]
1134 pub fn custom_leaf(node: CustomLeafNode) -> Self {
1135 Self::CustomLeaf(Box::new(node))
1136 }
1137
1138 #[must_use]
1140 pub fn split(node: SplitNode) -> Self {
1141 Self::Split(Box::new(node))
1142 }
1143
1144 #[must_use]
1146 pub const fn join(node: JoinNode) -> Self {
1147 Self::Join(node)
1148 }
1149
1150 #[must_use]
1152 pub fn partitioned_step(node: PartitionedStepNode) -> Self {
1153 Self::PartitionedStep(Box::new(node))
1154 }
1155
1156 #[must_use]
1158 pub const fn id(&self) -> &NodeId {
1159 match self {
1160 Self::Step(node) => node.id(),
1161 Self::Decision(node) => node.id(),
1162 Self::NestedJob(node) => node.id(),
1163 Self::CustomLeaf(node) => node.id(),
1164 Self::Split(node) => node.id(),
1165 Self::Join(node) => node.id(),
1166 Self::PartitionedStep(node) => node.id(),
1167 }
1168 }
1169
1170 fn manifest_value(&self) -> Value {
1171 match self {
1172 Self::Step(node) => node.manifest_value(),
1173 Self::Decision(node) => node.manifest_value(),
1174 Self::NestedJob(node) => node.manifest_value(),
1175 Self::CustomLeaf(node) => node.manifest_value(),
1176 Self::Split(node) => node.manifest_value(),
1177 Self::Join(node) => node.manifest_value(),
1178 Self::PartitionedStep(node) => node.manifest_value(),
1179 }
1180 }
1181}
1182
1183#[derive(Clone, Debug, Eq, PartialEq)]
1185pub struct FlowTransition {
1186 source: NodeId,
1187 pattern: ExitPattern,
1188 target: FlowTarget,
1189}
1190
1191impl FlowTransition {
1192 #[must_use]
1194 pub const fn new(source: NodeId, pattern: ExitPattern, target: FlowTarget) -> Self {
1195 Self {
1196 source,
1197 pattern,
1198 target,
1199 }
1200 }
1201
1202 #[must_use]
1204 pub const fn source(&self) -> &NodeId {
1205 &self.source
1206 }
1207
1208 #[must_use]
1210 pub const fn pattern(&self) -> &ExitPattern {
1211 &self.pattern
1212 }
1213
1214 #[must_use]
1216 pub const fn target(&self) -> &FlowTarget {
1217 &self.target
1218 }
1219
1220 fn manifest_value(&self) -> Value {
1221 json!({
1222 "pattern": self.pattern.as_str(),
1223 "source": self.source.as_str(),
1224 "target": flow_target_manifest(&self.target)
1225 })
1226 }
1227}
1228
1229#[derive(Clone, Debug, Default, Eq, PartialEq)]
1234pub struct FlowGraph {
1235 entry: Option<NodeId>,
1236 nodes: Vec<FlowNode>,
1237 transitions: Vec<FlowTransition>,
1238 nested_flows: Vec<NestedFlow>,
1239 scoped_components: Vec<ScopedComponentDefinition>,
1240 parameter_incrementer: Option<ParameterIncrementerIdentity>,
1241 job_restart_policy: RestartPolicy,
1242}
1243
1244impl FlowGraph {
1245 #[must_use]
1247 pub fn new(entry: NodeId) -> Self {
1248 Self {
1249 entry: Some(entry),
1250 nodes: Vec::new(),
1251 transitions: Vec::new(),
1252 nested_flows: Vec::new(),
1253 scoped_components: Vec::new(),
1254 parameter_incrementer: None,
1255 job_restart_policy: RestartPolicy::Restartable,
1256 }
1257 }
1258
1259 #[must_use]
1261 pub fn with_node(mut self, node: FlowNode) -> Self {
1262 self.nodes.push(node);
1263 self
1264 }
1265
1266 #[must_use]
1268 pub fn with_nested_flow(mut self, flow: NestedFlow) -> Self {
1269 self.nested_flows.push(flow);
1270 self
1271 }
1272
1273 #[must_use]
1278 pub fn with_scoped_component(mut self, component: ScopedComponentDefinition) -> Self {
1279 self.scoped_components.push(component);
1280 self
1281 }
1282
1283 #[must_use]
1288 pub fn with_parameter_incrementer_identity(
1289 mut self,
1290 identity: ParameterIncrementerIdentity,
1291 ) -> Self {
1292 self.parameter_incrementer = Some(identity);
1293 self
1294 }
1295
1296 #[must_use]
1302 pub const fn with_job_restart_policy(mut self, policy: RestartPolicy) -> Self {
1303 self.job_restart_policy = policy;
1304 self
1305 }
1306
1307 #[must_use]
1309 pub const fn job_restart_policy(&self) -> RestartPolicy {
1310 self.job_restart_policy
1311 }
1312
1313 #[must_use]
1315 pub const fn entry(&self) -> Option<&NodeId> {
1316 self.entry.as_ref()
1317 }
1318
1319 fn requires_advanced_format(&self) -> bool {
1320 self.job_restart_policy == RestartPolicy::NotRestartable
1321 || self.parameter_incrementer.is_some()
1322 || !self.scoped_components.is_empty()
1323 || !self.nested_flows.is_empty()
1324 || self.nodes.iter().any(|node| {
1325 node.has_nonrestartable_step()
1326 || node.has_repeat_definition()
1327 || match node {
1328 FlowNode::NestedJob(_) | FlowNode::CustomLeaf(_) => true,
1329 FlowNode::Split(split) => {
1330 split.branches().iter().any(|branch| branch.flow.is_some())
1331 }
1332 _ => false,
1333 }
1334 })
1335 }
1336
1337 #[must_use]
1339 pub fn with_transition(mut self, transition: FlowTransition) -> Self {
1340 self.transitions.push(transition);
1341 self
1342 }
1343
1344 pub fn with_sequence(self, source: NodeId, next: FlowTarget) -> Result<Self, PlanError> {
1356 Ok(self
1357 .with_transition(FlowTransition::new(
1358 source.clone(),
1359 ExitPattern::new("FAILED")?,
1360 FlowTarget::Terminal(TerminalKind::Fail),
1361 ))
1362 .with_transition(FlowTransition::new(source, ExitPattern::new("*")?, next)))
1363 }
1364
1365 pub fn compile(
1375 self,
1376 job_name: &JobName,
1377 revision: DefinitionRevision,
1378 ) -> Result<CompiledExecutionPlan, PlanError> {
1379 if self.requires_advanced_format() {
1380 return advanced::compile(self, job_name, revision);
1381 }
1382 let entry = self.entry.ok_or(PlanError::MissingEntryNode)?;
1383 if self.nodes.len() > MAX_NODES {
1384 return Err(PlanError::TooManyNodes { max: MAX_NODES });
1385 }
1386 if self.transitions.len() > MAX_TRANSITIONS {
1387 return Err(PlanError::TooManyTransitions {
1388 max: MAX_TRANSITIONS,
1389 });
1390 }
1391
1392 let mut nodes = BTreeMap::new();
1393 for node in self.nodes {
1394 if nodes.insert(node.id().clone(), node.clone()).is_some() {
1395 return Err(PlanError::DuplicateNodeId {
1396 node: node.id().clone(),
1397 });
1398 }
1399 }
1400 if !nodes.contains_key(&entry) {
1401 return Err(PlanError::UndefinedNode {
1402 node: entry.clone(),
1403 });
1404 }
1405 let local_scale = check_local_scale_subset(&entry, &nodes)?;
1406
1407 let mut outgoing: BTreeMap<NodeId, Vec<FlowTransition>> = BTreeMap::new();
1408 for transition in self.transitions {
1409 if !nodes.contains_key(transition.source()) {
1410 return Err(PlanError::UndefinedNode {
1411 node: transition.source().clone(),
1412 });
1413 }
1414 if let FlowTarget::Node(target) = transition.target()
1415 && !nodes.contains_key(target)
1416 {
1417 return Err(PlanError::UndefinedNode {
1418 node: target.clone(),
1419 });
1420 }
1421 if let FlowTarget::Node(target) = transition.target()
1422 && matches!(nodes.get(target), Some(FlowNode::Join(_)))
1423 {
1424 return Err(PlanError::JoinHasExternalEntry {
1425 join: target.clone(),
1426 });
1427 }
1428 if matches!(nodes.get(transition.source()), Some(FlowNode::Split(_))) {
1429 return Err(PlanError::SplitHasExplicitTransition {
1430 split: transition.source().clone(),
1431 });
1432 }
1433 let edges = outgoing.entry(transition.source().clone()).or_default();
1434 if edges.len() == MAX_OUTGOING_TRANSITIONS {
1435 return Err(PlanError::TooManyOutgoingTransitions {
1436 node: transition.source().clone(),
1437 max: MAX_OUTGOING_TRANSITIONS,
1438 });
1439 }
1440 edges.push(transition);
1441 }
1442
1443 for (id, node) in &nodes {
1444 if matches!(node, FlowNode::Split(_)) {
1445 continue;
1446 }
1447 let edges = outgoing
1448 .get(id)
1449 .filter(|edges| !edges.is_empty())
1450 .ok_or_else(|| PlanError::MissingTransition { node: id.clone() })?;
1451 check_unambiguous(id, edges)?;
1452 }
1453
1454 let mut compiled: BTreeMap<NodeId, Vec<FlowTransition>> = outgoing;
1455 for edges in compiled.values_mut() {
1456 edges.sort_by(|left, right| {
1457 right
1458 .pattern()
1459 .specificity()
1460 .cmp(&left.pattern().specificity())
1461 .then_with(|| left.pattern().cmp(right.pattern()))
1462 .then_with(|| left.target().sort_key().cmp(&right.target().sort_key()))
1463 });
1464 }
1465
1466 check_reachable_and_acyclic(&entry, &nodes, &compiled)?;
1467
1468 let manifest = flow_manifest(job_name, &entry, &nodes, &compiled, local_scale);
1469 let canonical = serde_json::to_vec(&manifest)
1470 .map_err(|_| PlanError::Manifest(DefinitionError::ManifestEncoding))?;
1471 let definition = DefinitionIdentity::from_flow_manifest(job_name, revision, &canonical)
1472 .map_err(PlanError::Manifest)?;
1473 Ok(CompiledExecutionPlan {
1474 definition,
1475 job_restart_policy: RestartPolicy::Restartable,
1476 parameter_incrementer: None,
1477 scoped_components: BTreeMap::new(),
1478 root_scope: CompiledFlowScope::new(entry.clone(), nodes.keys().cloned().collect()),
1479 entry,
1480 nodes,
1481 transitions: compiled,
1482 split_branch_scopes: BTreeMap::new(),
1483 nested_scopes: BTreeMap::new(),
1484 decision_sequences: BTreeMap::new(),
1485 })
1486 }
1487}
1488
1489fn check_local_scale_subset(
1490 entry: &NodeId,
1491 nodes: &BTreeMap<NodeId, FlowNode>,
1492) -> Result<bool, PlanError> {
1493 let mut embedded_ids = BTreeSet::new();
1494 let mut join_owners: BTreeMap<NodeId, NodeId> = BTreeMap::new();
1495 let mut local_scale = false;
1496 for (id, node) in nodes {
1497 match node {
1498 FlowNode::Split(split) => {
1499 local_scale = true;
1500 if id == entry {
1501 return Err(PlanError::SplitIsEntry { split: id.clone() });
1502 }
1503 if !(2..=MAX_SPLIT_BRANCHES).contains(&split.branches().len()) {
1504 return Err(PlanError::InvalidSplitBranchCount {
1505 split: id.clone(),
1506 min: 2,
1507 max: MAX_SPLIT_BRANCHES,
1508 });
1509 }
1510 if usize::from(split.budget().max_parallel_branches()) > split.branches().len() {
1511 return Err(PlanError::ParallelBudgetExceedsBranches {
1512 split: id.clone(),
1513 branches: split.branches().len(),
1514 });
1515 }
1516 if !matches!(nodes.get(split.join()), Some(FlowNode::Join(_))) {
1517 return Err(PlanError::InvalidSplitJoin {
1518 split: id.clone(),
1519 join: split.join().clone(),
1520 });
1521 }
1522 if let Some(first) = join_owners.insert(split.join().clone(), id.clone()) {
1523 return Err(PlanError::JoinHasMultipleOwners {
1524 join: split.join().clone(),
1525 first,
1526 second: id.clone(),
1527 });
1528 }
1529 for branch in split.branches() {
1530 if !(1..=MAX_BRANCH_STEPS).contains(&branch.steps().len()) {
1531 return Err(PlanError::InvalidBranchLength {
1532 split: id.clone(),
1533 max: MAX_BRANCH_STEPS,
1534 });
1535 }
1536 for step in branch.steps() {
1537 if nodes.contains_key(step.id()) || !embedded_ids.insert(step.id().clone())
1538 {
1539 return Err(PlanError::DuplicateNodeId {
1540 node: step.id().clone(),
1541 });
1542 }
1543 }
1544 }
1545 }
1546 FlowNode::Join(_) => {
1547 local_scale = true;
1548 }
1549 FlowNode::PartitionedStep(partitioned) => {
1550 local_scale = true;
1551 let worker = partitioned.worker().id();
1552 if nodes.contains_key(worker) || !embedded_ids.insert(worker.clone()) {
1553 return Err(PlanError::DuplicateNodeId {
1554 node: worker.clone(),
1555 });
1556 }
1557 }
1558 FlowNode::Step(_)
1559 | FlowNode::Decision(_)
1560 | FlowNode::NestedJob(_)
1561 | FlowNode::CustomLeaf(_) => {}
1562 }
1563 }
1564 if nodes.len().saturating_add(embedded_ids.len()) > MAX_NODES {
1565 return Err(PlanError::TooManyNodes { max: MAX_NODES });
1566 }
1567 for (id, node) in nodes {
1568 if matches!(node, FlowNode::Join(_)) && !join_owners.contains_key(id) {
1569 return Err(PlanError::OrphanJoin { join: id.clone() });
1570 }
1571 }
1572 Ok(local_scale)
1573}
1574
1575fn check_unambiguous(node: &NodeId, edges: &[FlowTransition]) -> Result<(), PlanError> {
1576 for (index, left) in edges.iter().enumerate() {
1577 for right in &edges[index + 1..] {
1578 if left.pattern().specificity() == right.pattern().specificity()
1579 && left.pattern().intersects(right.pattern())
1580 {
1581 return Err(PlanError::AmbiguousTransition {
1582 node: node.clone(),
1583 first: left.pattern().clone(),
1584 second: right.pattern().clone(),
1585 });
1586 }
1587 }
1588 }
1589 Ok(())
1590}
1591
1592fn check_reachable_and_acyclic(
1593 entry: &NodeId,
1594 nodes: &BTreeMap<NodeId, FlowNode>,
1595 transitions: &BTreeMap<NodeId, Vec<FlowTransition>>,
1596) -> Result<(), PlanError> {
1597 let mut visited = BTreeSet::new();
1598 let mut on_path = BTreeSet::new();
1599 visit(entry, nodes, transitions, &mut visited, &mut on_path)?;
1600 for id in nodes.keys() {
1601 if !visited.contains(id) {
1602 return Err(PlanError::UnreachableNode { node: id.clone() });
1603 }
1604 }
1605 Ok(())
1606}
1607
1608fn visit(
1609 node: &NodeId,
1610 nodes: &BTreeMap<NodeId, FlowNode>,
1611 transitions: &BTreeMap<NodeId, Vec<FlowTransition>>,
1612 visited: &mut BTreeSet<NodeId>,
1613 on_path: &mut BTreeSet<NodeId>,
1614) -> Result<(), PlanError> {
1615 if on_path.contains(node) {
1616 return Err(PlanError::CyclicGraph { node: node.clone() });
1617 }
1618 if !visited.insert(node.clone()) {
1619 return Ok(());
1620 }
1621 on_path.insert(node.clone());
1622 if let Some(FlowNode::Split(split)) = nodes.get(node) {
1623 visit(split.join(), nodes, transitions, visited, on_path)?;
1624 }
1625 if let Some(edges) = transitions.get(node) {
1626 for edge in edges {
1627 if let FlowTarget::Node(target) = edge.target() {
1628 visit(target, nodes, transitions, visited, on_path)?;
1629 }
1630 }
1631 }
1632 on_path.remove(node);
1633 Ok(())
1634}
1635
1636fn start_controls_manifest(controls: StartControls) -> Value {
1643 let mut value = json!({
1644 "allow_start_if_complete": controls.allow_start_if_complete(),
1645 "start_limit": controls.start_limit().get()
1646 });
1647 if controls.restart_policy() == RestartPolicy::NotRestartable
1648 && let Some(object) = value.as_object_mut()
1649 {
1650 object.insert(
1651 "restart_policy".to_owned(),
1652 Value::String("not_restartable".to_owned()),
1653 );
1654 }
1655 value
1656}
1657
1658fn flow_target_manifest(target: &FlowTarget) -> Value {
1660 match target {
1661 FlowTarget::Node(id) => json!({ "node": id.as_str() }),
1662 FlowTarget::Terminal(kind) => json!({ "terminal": kind.as_str() }),
1663 }
1664}
1665
1666fn chunk_declaration_manifest(revisions: &ChunkComponentRevisions) -> Value {
1672 let mut value = json!({
1673 "checkpoint": {
1674 "schema": revisions.checkpoint_schema().as_str(),
1675 "version": revisions.checkpoint_schema_version().get()
1676 },
1677 "components": {
1678 "checkpoint": revisions.checkpoint().as_str(),
1679 "processor": revisions.processor().as_str(),
1680 "reader": revisions.reader().as_str(),
1681 "writer": revisions.writer().as_str()
1682 },
1683 "context": {
1684 "schema": revisions.context_schema().as_str(),
1685 "version": revisions.context_schema_version().get()
1686 },
1687 "delivery_mode": revisions.delivery_mode().manifest_name()
1688 });
1689 if revisions.in_flight_policy() == InFlightPolicy::RollbackChunk
1690 && let Some(object) = value.as_object_mut()
1691 {
1692 object.insert(
1693 "in_flight_policy".to_owned(),
1694 Value::String("rollback_chunk".to_owned()),
1695 );
1696 }
1697 value
1698}
1699
1700fn fault_manifest_value(policy: &FaultPolicy) -> Value {
1701 let backoff = policy.backoff();
1702 let rules: Vec<Value> = policy
1703 .classifier()
1704 .rules()
1705 .iter()
1706 .map(|rule| {
1707 json!({
1708 "category": rule.category().as_str(),
1709 "phase": rule.phase().as_str(),
1710 "retryable": rule.action().is_retryable(),
1711 "skip": rule
1712 .action()
1713 .skip_disposition()
1714 .map_or(Value::Null, |skip| Value::String(skip.as_str().to_owned()))
1715 })
1716 })
1717 .collect();
1718 json!({
1719 "backoff": {
1720 "initial_ms": u64::try_from(backoff.initial().as_millis()).unwrap_or(u64::MAX),
1721 "kind": backoff.kind().as_str(),
1722 "maximum_ms": u64::try_from(backoff.maximum().as_millis()).unwrap_or(u64::MAX),
1723 "multiplier": backoff.multiplier()
1724 },
1725 "classifier": {
1726 "revision": policy.classifier().revision().as_str(),
1727 "rules": rules
1728 },
1729 "retry_limit": policy.retry_limit().get(),
1730 "retry_state_limit": policy.retry_state_limit().get(),
1731 "skip_limit": policy.skip_limit().get()
1732 })
1733}
1734
1735fn flow_manifest(
1744 job_name: &JobName,
1745 entry: &NodeId,
1746 nodes: &BTreeMap<NodeId, FlowNode>,
1747 transitions: &BTreeMap<NodeId, Vec<FlowTransition>>,
1748 local_scale: bool,
1749) -> Value {
1750 let node_values: Vec<Value> = nodes.values().map(FlowNode::manifest_value).collect();
1751 let transition_values: Vec<Value> = transitions
1752 .values()
1753 .flat_map(|edges| edges.iter().map(FlowTransition::manifest_value))
1754 .collect();
1755 json!({
1756 "entry": entry.as_str(),
1757 "format": if local_scale {
1758 oxide_batch_core::MANIFEST_FORMAT_LOCAL_SCALE
1759 } else {
1760 oxide_batch_core::MANIFEST_FORMAT_FLOW
1761 },
1762 "job": job_name.as_str(),
1763 "nodes": node_values,
1764 "transitions": transition_values
1765 })
1766}
1767
1768#[derive(Clone, Debug, Eq, PartialEq)]
1775pub struct CompiledExecutionPlan {
1776 definition: DefinitionIdentity,
1777 job_restart_policy: RestartPolicy,
1778 parameter_incrementer: Option<ParameterIncrementerIdentity>,
1779 scoped_components: BTreeMap<(ScopeKind, ScopedComponentId), ScopedComponentDefinition>,
1780 entry: NodeId,
1781 root_scope: CompiledFlowScope,
1782 nodes: BTreeMap<NodeId, FlowNode>,
1783 transitions: BTreeMap<NodeId, Vec<FlowTransition>>,
1784 split_branch_scopes: BTreeMap<(NodeId, usize), CompiledFlowScope>,
1785 nested_scopes: BTreeMap<NodeId, CompiledFlowScope>,
1786 decision_sequences: BTreeMap<NodeId, u64>,
1787}
1788
1789impl CompiledExecutionPlan {
1790 #[doc(hidden)]
1797 pub fn compatibility_one_step(
1798 definition: DefinitionIdentity,
1799 step: StepNode,
1800 ) -> Result<Self, PlanError> {
1801 let entry = step.id().clone();
1802 let mut nodes = BTreeMap::new();
1803 nodes.insert(entry.clone(), FlowNode::step(step));
1804 let mut edges = Vec::with_capacity(3);
1805 for (code, terminal) in [
1806 ("COMPLETED", TerminalKind::Complete),
1807 ("FAILED", TerminalKind::Fail),
1808 ("STOPPED", TerminalKind::Stop),
1809 ] {
1810 edges.push(FlowTransition::new(
1811 entry.clone(),
1812 ExitPattern::new(code)?,
1813 FlowTarget::Terminal(terminal),
1814 ));
1815 }
1816 check_unambiguous(&entry, &edges)?;
1817 let mut transitions = BTreeMap::new();
1818 transitions.insert(entry.clone(), edges);
1819 Ok(Self {
1820 definition,
1821 job_restart_policy: RestartPolicy::Restartable,
1822 parameter_incrementer: None,
1823 scoped_components: BTreeMap::new(),
1824 root_scope: CompiledFlowScope::new(entry.clone(), nodes.keys().cloned().collect()),
1825 entry,
1826 nodes,
1827 transitions,
1828 split_branch_scopes: BTreeMap::new(),
1829 nested_scopes: BTreeMap::new(),
1830 decision_sequences: BTreeMap::new(),
1831 })
1832 }
1833
1834 #[must_use]
1836 pub const fn definition_identity(&self) -> &DefinitionIdentity {
1837 &self.definition
1838 }
1839
1840 #[must_use]
1842 pub const fn job_restart_policy(&self) -> RestartPolicy {
1843 self.job_restart_policy
1844 }
1845
1846 #[must_use]
1848 pub const fn parameter_incrementer_identity(&self) -> Option<&ParameterIncrementerIdentity> {
1849 self.parameter_incrementer.as_ref()
1850 }
1851
1852 #[must_use]
1854 pub fn scoped_components(&self) -> impl ExactSizeIterator<Item = &ScopedComponentDefinition> {
1855 self.scoped_components.values()
1856 }
1857
1858 #[must_use]
1860 pub fn scoped_component(
1861 &self,
1862 scope: ScopeKind,
1863 id: &ScopedComponentId,
1864 ) -> Option<&ScopedComponentDefinition> {
1865 self.scoped_components.get(&(scope, id.clone()))
1866 }
1867
1868 #[must_use]
1870 pub const fn manifest_format(&self) -> u16 {
1871 self.definition.manifest_format()
1872 }
1873
1874 #[must_use]
1876 pub const fn fingerprint(&self) -> &[u8; 32] {
1877 self.definition.manifest_digest()
1878 }
1879
1880 #[must_use]
1882 pub const fn entry(&self) -> &NodeId {
1883 &self.entry
1884 }
1885
1886 #[must_use]
1888 pub const fn root_scope(&self) -> &CompiledFlowScope {
1889 &self.root_scope
1890 }
1891
1892 #[must_use]
1894 pub fn split_branch_scope(&self, split: &NodeId, ordinal: usize) -> Option<&CompiledFlowScope> {
1895 self.split_branch_scopes.get(&(split.clone(), ordinal))
1896 }
1897
1898 #[must_use]
1900 pub fn nested_scope(&self, owner: &NodeId) -> Option<&CompiledFlowScope> {
1901 self.nested_scopes.get(owner)
1902 }
1903
1904 #[must_use]
1908 pub fn decision_sequence(&self, source: &NodeId) -> Option<u64> {
1909 self.decision_sequences.get(source).copied()
1910 }
1911
1912 #[must_use]
1914 pub fn node_count(&self) -> usize {
1915 self.nodes.len()
1916 }
1917
1918 #[must_use]
1920 pub fn transition_count(&self) -> usize {
1921 self.transitions.values().map(Vec::len).sum()
1922 }
1923
1924 #[must_use]
1926 pub fn node(&self, id: &NodeId) -> Option<&FlowNode> {
1927 self.nodes.get(id)
1928 }
1929
1930 #[must_use]
1936 pub fn nodes(&self) -> impl ExactSizeIterator<Item = (&NodeId, &FlowNode)> {
1937 self.nodes.iter()
1938 }
1939
1940 #[must_use]
1945 pub fn transitions(&self, id: &NodeId) -> &[FlowTransition] {
1946 self.transitions.get(id).map_or(&[], Vec::as_slice)
1947 }
1948
1949 pub fn select_target(
1958 &self,
1959 id: &NodeId,
1960 code: &ExitCode,
1961 ) -> Result<&FlowTarget, FlowSelectionError> {
1962 let edges = self
1963 .transitions
1964 .get(id)
1965 .ok_or_else(|| FlowSelectionError::UnknownNode { node: id.clone() })?;
1966 edges
1967 .iter()
1968 .find(|edge| edge.pattern().matches(code))
1969 .map(FlowTransition::target)
1970 .ok_or_else(|| FlowSelectionError::UnmappedExitOutcome {
1971 node: id.clone(),
1972 code: code.clone(),
1973 })
1974 }
1975}
1976
1977#[derive(Clone, Debug, Eq, PartialEq)]
1979#[non_exhaustive]
1980pub enum PlanError {
1981 MissingEntryNode,
1983 DuplicateNodeId {
1985 node: NodeId,
1987 },
1988 UndefinedNode {
1990 node: NodeId,
1992 },
1993 MissingTransition {
1995 node: NodeId,
1997 },
1998 AmbiguousTransition {
2000 node: NodeId,
2002 first: ExitPattern,
2004 second: ExitPattern,
2006 },
2007 UnreachableNode {
2009 node: NodeId,
2011 },
2012 CyclicGraph {
2014 node: NodeId,
2016 },
2017 TooManyNodes {
2019 max: usize,
2021 },
2022 TooManyTransitions {
2024 max: usize,
2026 },
2027 TooManyOutgoingTransitions {
2029 node: NodeId,
2031 max: usize,
2033 },
2034 InvalidPattern {
2036 max_bytes: usize,
2038 },
2039 ZeroDecisionInputVersion,
2041 InvalidSplitBranchCount {
2043 split: NodeId,
2045 min: usize,
2047 max: usize,
2049 },
2050 InvalidBranchLength {
2052 split: NodeId,
2054 max: usize,
2056 },
2057 SplitIsEntry {
2059 split: NodeId,
2061 },
2062 InvalidSplitJoin {
2064 split: NodeId,
2066 join: NodeId,
2068 },
2069 JoinHasMultipleOwners {
2071 join: NodeId,
2073 first: NodeId,
2075 second: NodeId,
2077 },
2078 OrphanJoin {
2080 join: NodeId,
2082 },
2083 JoinHasExternalEntry {
2085 join: NodeId,
2087 },
2088 SplitHasExplicitTransition {
2090 split: NodeId,
2092 },
2093 ParallelBudgetExceedsBranches {
2095 split: NodeId,
2097 branches: usize,
2099 },
2100 InvalidParallelBranchBudget {
2102 max: usize,
2104 },
2105 InvalidPartitionWorkerBudget {
2107 max: u8,
2109 },
2110 InsufficientPoolCapacity {
2112 required: u32,
2114 configured: u32,
2116 },
2117 InvalidPartitionCount {
2119 max: u16,
2121 },
2122 CompositionDepthExceeded {
2124 max: usize,
2126 },
2127 UnmappedNestedFlowExit {
2129 flow: NodeId,
2131 code: ExitCode,
2133 },
2134 InvalidSelectorPath {
2136 max_bytes: usize,
2138 max_segments: usize,
2140 },
2141 NestedJobMissingChildIdentity {
2143 node: NodeId,
2145 },
2146 TooManyScopedComponents {
2148 max: usize,
2150 },
2151 DuplicateScopedComponent {
2153 scope: ScopeKind,
2155 component: ScopedComponentId,
2157 },
2158 DuplicateRepeatId {
2160 repeat: RepeatId,
2162 },
2163 TooManyNestedJobParameters {
2165 node: NodeId,
2167 max: usize,
2169 },
2170 DuplicateNestedJobParameter {
2172 node: NodeId,
2174 parameter: ParameterName,
2176 },
2177 Token(DefinitionError),
2179 Manifest(DefinitionError),
2181}
2182
2183impl fmt::Display for PlanError {
2184 #[allow(
2185 clippy::too_many_lines,
2186 reason = "each typed plan rejection retains one stable redacted diagnostic"
2187 )]
2188 fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
2189 match self {
2190 Self::MissingEntryNode => formatter.write_str("flow graph has no entry node"),
2191 Self::DuplicateNodeId { node } => {
2192 write!(
2193 formatter,
2194 "node {} is declared more than once",
2195 node.as_str()
2196 )
2197 }
2198 Self::UndefinedNode { node } => {
2199 write!(formatter, "node {} is not declared", node.as_str())
2200 }
2201 Self::MissingTransition { node } => {
2202 write!(
2203 formatter,
2204 "node {} has no outgoing transition",
2205 node.as_str()
2206 )
2207 }
2208 Self::AmbiguousTransition {
2209 node,
2210 first,
2211 second,
2212 } => write!(
2213 formatter,
2214 "node {} patterns {first} and {second} are equally specific and overlap",
2215 node.as_str()
2216 ),
2217 Self::UnreachableNode { node } => {
2218 write!(
2219 formatter,
2220 "node {} is unreachable from the entry node",
2221 node.as_str()
2222 )
2223 }
2224 Self::CyclicGraph { node } => {
2225 write!(formatter, "node {} closes a cycle", node.as_str())
2226 }
2227 Self::TooManyNodes { max } => write!(formatter, "flow graph exceeds {max} nodes"),
2228 Self::TooManyTransitions { max } => {
2229 write!(formatter, "flow graph exceeds {max} transitions")
2230 }
2231 Self::TooManyOutgoingTransitions { node, max } => write!(
2232 formatter,
2233 "node {} exceeds {max} outgoing transitions",
2234 node.as_str()
2235 ),
2236 Self::InvalidPattern { max_bytes } => write!(
2237 formatter,
2238 "exit pattern must be 1 to {max_bytes} bytes without control characters"
2239 ),
2240 Self::ZeroDecisionInputVersion => {
2241 formatter.write_str("decision input version must be nonzero")
2242 }
2243 Self::InvalidSplitBranchCount { split, min, max } => write!(
2244 formatter,
2245 "split {} must declare {min} to {max} branches",
2246 split.as_str()
2247 ),
2248 Self::InvalidBranchLength { split, max } => write!(
2249 formatter,
2250 "split {} branches must declare 1 to {max} steps",
2251 split.as_str()
2252 ),
2253 Self::SplitIsEntry { split } => {
2254 write!(
2255 formatter,
2256 "split {} cannot be the entry node",
2257 split.as_str()
2258 )
2259 }
2260 Self::InvalidSplitJoin { split, join } => write!(
2261 formatter,
2262 "split {} does not own declared join {}",
2263 split.as_str(),
2264 join.as_str()
2265 ),
2266 Self::JoinHasMultipleOwners {
2267 join,
2268 first,
2269 second,
2270 } => write!(
2271 formatter,
2272 "join {} is owned by both splits {} and {}",
2273 join.as_str(),
2274 first.as_str(),
2275 second.as_str()
2276 ),
2277 Self::OrphanJoin { join } => {
2278 write!(formatter, "join {} has no owning split", join.as_str())
2279 }
2280 Self::JoinHasExternalEntry { join } => write!(
2281 formatter,
2282 "join {} can be entered only by its owning split",
2283 join.as_str()
2284 ),
2285 Self::SplitHasExplicitTransition { split } => write!(
2286 formatter,
2287 "split {} reaches only its declared join",
2288 split.as_str()
2289 ),
2290 Self::ParallelBudgetExceedsBranches { split, branches } => write!(
2291 formatter,
2292 "split {} parallel budget exceeds its {branches} branches",
2293 split.as_str()
2294 ),
2295 Self::InvalidParallelBranchBudget { max } => {
2296 write!(formatter, "parallel branch budget must be 1 to {max}")
2297 }
2298 Self::InvalidPartitionWorkerBudget { max } => {
2299 write!(formatter, "partition worker budget must be 1 to {max}")
2300 }
2301 Self::InsufficientPoolCapacity {
2302 required,
2303 configured,
2304 } => write!(
2305 formatter,
2306 "repository pool size {configured} cannot supply required capacity {required}"
2307 ),
2308 Self::InvalidPartitionCount { max } => {
2309 write!(formatter, "partition count must be 1 to {max}")
2310 }
2311 Self::CompositionDepthExceeded { max } => {
2312 write!(formatter, "flow composition exceeds depth {max}")
2313 }
2314 Self::InvalidSelectorPath {
2315 max_bytes,
2316 max_segments,
2317 } => write!(
2318 formatter,
2319 "selector path must contain 1 to {max_segments} bounded segments within {max_bytes} bytes"
2320 ),
2321 Self::NestedJobMissingChildIdentity { node } => write!(
2322 formatter,
2323 "nested job {} requires a bound child definition identity",
2324 node.as_str()
2325 ),
2326 Self::TooManyScopedComponents { max } => {
2327 write!(formatter, "flow graph exceeds {max} scoped components")
2328 }
2329 Self::DuplicateScopedComponent { scope, component } => write!(
2330 formatter,
2331 "{} scope component {} is declared more than once",
2332 scope.as_str(),
2333 component.as_str()
2334 ),
2335 Self::DuplicateRepeatId { repeat } => write!(
2336 formatter,
2337 "repeat {} is declared more than once in the compiled plan",
2338 repeat.as_str()
2339 ),
2340 Self::TooManyNestedJobParameters { node, max } => write!(
2341 formatter,
2342 "nested job {} exceeds {max} child parameters",
2343 node.as_str()
2344 ),
2345 Self::DuplicateNestedJobParameter { node, parameter } => write!(
2346 formatter,
2347 "nested job {} maps child parameter {} more than once",
2348 node.as_str(),
2349 parameter.as_str()
2350 ),
2351 Self::UnmappedNestedFlowExit { flow, code } => write!(
2352 formatter,
2353 "nested flow {} declares no transition for terminal outcome {code}",
2354 flow.as_str()
2355 ),
2356 Self::Token(error) => write!(formatter, "flow graph token is invalid: {error}"),
2357 Self::Manifest(error) => {
2358 write!(formatter, "flow manifest could not be encoded: {error}")
2359 }
2360 }
2361 }
2362}
2363
2364impl Error for PlanError {
2365 fn source(&self) -> Option<&(dyn Error + 'static)> {
2366 match self {
2367 Self::Token(error) | Self::Manifest(error) => Some(error),
2368 _ => None,
2369 }
2370 }
2371}
2372
2373impl From<DefinitionError> for PlanError {
2374 fn from(error: DefinitionError) -> Self {
2375 Self::Token(error)
2376 }
2377}
2378
2379#[derive(Clone, Debug, Eq, PartialEq)]
2381#[non_exhaustive]
2382pub enum FlowSelectionError {
2383 UnknownNode {
2385 node: NodeId,
2387 },
2388 UnmappedExitOutcome {
2390 node: NodeId,
2392 code: ExitCode,
2394 },
2395}
2396
2397impl fmt::Display for FlowSelectionError {
2398 fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
2399 match self {
2400 Self::UnknownNode { node } => {
2401 write!(
2402 formatter,
2403 "node {} is not part of the compiled plan",
2404 node.as_str()
2405 )
2406 }
2407 Self::UnmappedExitOutcome { node, code } => write!(
2408 formatter,
2409 "node {} declares no transition for exit outcome {code}",
2410 node.as_str()
2411 ),
2412 }
2413 }
2414}
2415
2416impl Error for FlowSelectionError {}