Skip to main content

oxide_batch_plan/
custom_leaf.rs

1use oxide_batch_core::{
2    ComponentRevision, DefinitionError, DefinitionTokenKind, FaultPolicy, NodeId, StartControls,
3    StateSchemaId, StateSchemaVersion, StepName, definition_token, validate_token,
4};
5use serde_json::{Value, json};
6
7use super::{fault_manifest_value, start_controls_manifest};
8
9definition_token!(
10    CustomLeafKind,
11    DefinitionTokenKind::Component,
12    "A stable application-owned kind identifier for one registered custom leaf."
13);
14
15/// One bounded registered custom-leaf declaration in a format-4 flow.
16///
17/// The declaration contains only restart-relevant meaning. Runtime locations,
18/// credentials, handler objects, repository handles, and deployment policy are
19/// deliberately absent from the definition fingerprint.
20#[derive(Clone, Debug, Eq, PartialEq)]
21pub struct CustomLeafNode {
22    id: NodeId,
23    step_name: StepName,
24    kind: CustomLeafKind,
25    handler_revision: ComponentRevision,
26    state_schema_id: StateSchemaId,
27    state_schema_version: StateSchemaVersion,
28    start: StartControls,
29    fault: Option<FaultPolicy>,
30    listeners: Vec<ComponentRevision>,
31}
32
33impl CustomLeafNode {
34    /// Declares one custom leaf with its exact handler and durable-state identity.
35    #[must_use]
36    pub const fn new(
37        id: NodeId,
38        step_name: StepName,
39        kind: CustomLeafKind,
40        handler_revision: ComponentRevision,
41        state_schema_id: StateSchemaId,
42        state_schema_version: StateSchemaVersion,
43    ) -> Self {
44        Self {
45            id,
46            step_name,
47            kind,
48            handler_revision,
49            state_schema_id,
50            state_schema_version,
51            start: StartControls::new(oxide_batch_core::StartLimit::UNRESTRICTED, false),
52            fault: None,
53            listeners: Vec::new(),
54        }
55    }
56
57    /// Applies restart-relevant start controls.
58    #[must_use]
59    pub const fn with_start_controls(mut self, start: StartControls) -> Self {
60        self.start = start;
61        self
62    }
63
64    /// Applies the framework fault policy executed around this leaf.
65    #[must_use]
66    pub fn with_fault_policy(mut self, fault: FaultPolicy) -> Self {
67        self.fault = Some(fault);
68        self
69    }
70
71    /// Adds one framework step-listener revision in deterministic before-order.
72    #[must_use]
73    pub fn with_listener_revision(mut self, listener: ComponentRevision) -> Self {
74        self.listeners.push(listener);
75        self
76    }
77
78    /// Borrows the stable logical node identifier.
79    #[must_use]
80    pub const fn id(&self) -> &NodeId {
81        &self.id
82    }
83
84    /// Borrows the framework-owned durable step name.
85    #[must_use]
86    pub const fn step_name(&self) -> &StepName {
87        &self.step_name
88    }
89
90    /// Borrows the stable custom-leaf kind selected at registration.
91    #[must_use]
92    pub const fn kind(&self) -> &CustomLeafKind {
93        &self.kind
94    }
95
96    /// Borrows the exact executable handler revision.
97    #[must_use]
98    pub const fn handler_revision(&self) -> &ComponentRevision {
99        &self.handler_revision
100    }
101
102    /// Borrows the durable custom-state schema identifier.
103    #[must_use]
104    pub const fn state_schema_id(&self) -> &StateSchemaId {
105        &self.state_schema_id
106    }
107
108    /// Returns the durable custom-state schema version.
109    #[must_use]
110    pub const fn state_schema_version(&self) -> StateSchemaVersion {
111        self.state_schema_version
112    }
113
114    /// Returns the framework start controls.
115    #[must_use]
116    pub const fn start_controls(&self) -> StartControls {
117        self.start
118    }
119
120    /// Borrows the optional framework fault policy.
121    #[must_use]
122    pub const fn fault_policy(&self) -> Option<&FaultPolicy> {
123        self.fault.as_ref()
124    }
125
126    /// Borrows registered framework listener revisions.
127    #[must_use]
128    pub fn listener_revisions(&self) -> &[ComponentRevision] {
129        &self.listeners
130    }
131
132    pub(super) fn manifest_value(&self) -> Value {
133        json!({
134            "handler_revision": self.handler_revision.as_str(),
135            "id": self.id.as_str(),
136            "kind": "custom_leaf",
137            "leaf_kind": self.kind.as_str(),
138            "listeners": self.listeners.iter().map(ComponentRevision::as_str).collect::<Vec<_>>(),
139            "policy": self.fault.as_ref().map_or(Value::Null, fault_manifest_value),
140            "start": start_controls_manifest(self.start),
141            "state_schema": {
142                "id": self.state_schema_id.as_str(),
143                "version": self.state_schema_version.get()
144            },
145            "step_name": self.step_name.as_str()
146        })
147    }
148}