Skip to main content

appcore_contracts/policy/
capability.rs

1// =============================================================================
2//        #######
3//     ###       ###     F: capability.rs
4//    ##   ## ##   ##    P: AppCore-Runtime
5//         ## ##
6//                       C: 2026/07/22 15:41:18 by dnettoRaw
7//    ##   ## ##   ##    U: 2026/07/23 10:59:21 by dnettoRaw
8//      ###########      S: 1.0.1-rc.8
9// =============================================================================
10
11//! Defines bounded capability contracts and behavior for this crate.
12
13use super::*;
14
15/// Ownership boundary for a capability declaration.
16#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize)]
17#[serde(rename_all = "snake_case")]
18pub enum CapabilityClass {
19    /// Infrastructure behavior owned and consumed by the Runtime.
20    Infrastructure,
21    /// Application behavior implemented by consumer code.
22    #[default]
23    Functional,
24}
25
26impl CapabilityClass {
27    fn is_functional(&self) -> bool {
28        *self == Self::Functional
29    }
30}
31
32/// Where a capability may be resolved.
33#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
34#[serde(rename_all = "snake_case")]
35pub enum CapabilityVisibility {
36    /// Only inside the current process.
37    Local,
38    /// Across compatible peers in the cluster.
39    Cluster,
40    /// Across peers belonging to the same tenant boundary.
41    Tenant,
42}
43
44/// Application declaration for one generic capability.
45#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
46pub struct CapabilityDeclaration {
47    id: CapabilityId,
48    #[serde(default, skip_serializing_if = "CapabilityClass::is_functional")]
49    class: CapabilityClass,
50    version: String,
51    mode: CapabilityMode,
52    visibility: CapabilityVisibility,
53    requires_leader: bool,
54    idempotency_required: bool,
55}
56
57impl CapabilityDeclaration {
58    /// Creates a capability declaration.
59    pub fn new(
60        id: CapabilityId,
61        version: impl Into<String>,
62        mode: CapabilityMode,
63        visibility: CapabilityVisibility,
64    ) -> ContractResult<Self> {
65        let declaration = Self {
66            id,
67            class: CapabilityClass::Functional,
68            version: version.into(),
69            mode,
70            visibility,
71            requires_leader: false,
72            idempotency_required: false,
73        };
74        declaration.validate()?;
75        Ok(declaration)
76    }
77
78    /// Classifies the capability as Runtime infrastructure or application behavior.
79    pub fn with_class(mut self, class: CapabilityClass) -> Self {
80        self.class = class;
81        self
82    }
83
84    /// Marks whether execution requires service leadership.
85    pub fn with_leadership(mut self, required: bool) -> Self {
86        self.requires_leader = required;
87        self
88    }
89
90    /// Marks whether command invocations require an idempotency key.
91    pub fn with_idempotency(mut self, required: bool) -> Self {
92        self.idempotency_required = required;
93        self
94    }
95
96    /// Returns the capability identity.
97    pub fn id(&self) -> &CapabilityId {
98        &self.id
99    }
100
101    /// Returns the capability ownership boundary.
102    pub fn class(&self) -> CapabilityClass {
103        self.class
104    }
105
106    /// Returns the declared capability version.
107    pub fn version(&self) -> &str {
108        &self.version
109    }
110
111    /// Returns the invocation mode.
112    pub fn mode(&self) -> CapabilityMode {
113        self.mode
114    }
115
116    /// Returns the visibility boundary.
117    pub fn visibility(&self) -> CapabilityVisibility {
118        self.visibility
119    }
120
121    /// Reports whether the capability requires leadership.
122    pub fn requires_leader(&self) -> bool {
123        self.requires_leader
124    }
125
126    /// Reports whether commands require an idempotency key.
127    pub fn idempotency_required(&self) -> bool {
128        self.idempotency_required
129    }
130
131    pub(crate) fn validate(&self) -> ContractResult<()> {
132        validate_text("capability.version", &self.version, 64)
133    }
134}
135
136/// Runtime and protocol versions required by an application.
137#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
138pub struct RuntimeRequirements {
139    minimum_runtime_version: String,
140    maximum_runtime_version: Option<String>,
141    protocol_version: String,
142    required_features: BTreeSet<FeatureId>,
143}
144
145impl RuntimeRequirements {
146    /// Creates minimum runtime and protocol requirements.
147    pub fn new(
148        minimum_runtime_version: impl Into<String>,
149        protocol_version: impl Into<String>,
150    ) -> ContractResult<Self> {
151        let requirements = Self {
152            minimum_runtime_version: minimum_runtime_version.into(),
153            maximum_runtime_version: None,
154            protocol_version: protocol_version.into(),
155            required_features: BTreeSet::new(),
156        };
157        requirements.validate()?;
158        Ok(requirements)
159    }
160
161    /// Adds an inclusive maximum runtime version.
162    pub fn with_maximum_runtime_version(
163        mut self,
164        version: impl Into<String>,
165    ) -> ContractResult<Self> {
166        let version = version.into();
167        validate_text("runtime.maximum_version", &version, 64)?;
168        self.maximum_runtime_version = Some(version);
169        Ok(self)
170    }
171
172    /// Adds a runtime feature required by the application.
173    pub fn with_required_feature(mut self, feature: FeatureId) -> Self {
174        self.required_features.insert(feature);
175        self
176    }
177
178    /// Returns the minimum compatible runtime version.
179    pub fn minimum_runtime_version(&self) -> &str {
180        &self.minimum_runtime_version
181    }
182
183    /// Returns the optional maximum compatible runtime version.
184    pub fn maximum_runtime_version(&self) -> Option<&str> {
185        self.maximum_runtime_version.as_deref()
186    }
187
188    /// Returns the required distributed protocol version.
189    pub fn protocol_version(&self) -> &str {
190        &self.protocol_version
191    }
192
193    /// Returns required runtime features.
194    pub fn required_features(&self) -> &BTreeSet<FeatureId> {
195        &self.required_features
196    }
197
198    pub(crate) fn validate(&self) -> ContractResult<()> {
199        validate_text("runtime.minimum_version", &self.minimum_runtime_version, 64)?;
200        validate_text("runtime.protocol_version", &self.protocol_version, 64)?;
201        if let Some(version) = &self.maximum_runtime_version {
202            validate_text("runtime.maximum_version", version, 64)?;
203        }
204        Ok(())
205    }
206}