canic_core/dto/
component_provisioning.rs

1//! Module: dto::component_provisioning
2//!
3//! Responsibility: carry one canonical Fleet Component provisioning plan across boundaries.
4//! Does not own: plan derivation, validation, persistence, root effects, or receipts.
5//! Boundary: the Coordinator retains the complete plan and sends each root only its exact batch.
6
7use crate::{
8    config::{ComponentDeploymentLabel, ComponentDeploymentLimits, ComponentDeploymentPurpose},
9    dto::fleet_registry::FleetRegistryVersion,
10    ids::{
11        ComponentBinding, ComponentDeploymentConfigurationDigest, ComponentGroupDeploymentId,
12        ComponentGroupMemberPath, ComponentGroupPlacementId, ComponentGroupSpecId, ComponentSpecId,
13        FleetBinding, FleetSubnetRootBinding, FleetSubnetRootReleaseSet,
14    },
15};
16use candid::{CandidType, Principal};
17use serde::{Deserialize, Serialize};
18
19/// Complete canonical provisioning authority retained before any root effect.
20#[derive(CandidType, Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
21#[serde(deny_unknown_fields)]
22pub struct FleetComponentProvisioningPlan {
23    pub fleet: FleetBinding,
24    pub fleet_registry: FleetRegistryVersion,
25    pub configuration_digest: ComponentDeploymentConfigurationDigest,
26    pub operation: FleetComponentProvisioningOperation,
27    pub directory_confirmation_roots: Vec<Principal>,
28    pub batches: Vec<FleetSubnetRootProvisioningBatch>,
29}
30
31/// Controller-authenticated command that durably freezes one complete plan.
32#[derive(CandidType, Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
33#[serde(deny_unknown_fields)]
34pub struct FleetComponentProvisioningPrepareRequest {
35    pub operation_id: [u8; 32],
36    pub plan: FleetComponentProvisioningPlan,
37}
38
39/// Controller-authenticated command advancing one exact Coordinator provisioning step.
40#[derive(CandidType, Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
41#[serde(deny_unknown_fields)]
42pub struct FleetComponentProvisioningAdvanceRequest {
43    pub operation_id: [u8; 32],
44    pub plan_hash: [u8; 32],
45    pub expected_phase: FleetComponentProvisioningPhase,
46    pub expected_accepted_root_count: u32,
47    pub expected_provisioned_root_count: u32,
48    pub expected_current_root: Option<FleetComponentProvisioningRootProgress>,
49    pub expected_directory_confirmed_root_count: u32,
50    pub expected_current_publication: Option<FleetComponentPublicationRootProgress>,
51    pub expected_runtime_activated_root_count: u32,
52    pub expected_current_activation: Option<FleetComponentActivationRootProgress>,
53}
54
55/// Exact root-local cursor copied from passive Coordinator status before one advance.
56#[derive(CandidType, Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
57#[serde(deny_unknown_fields)]
58pub struct FleetComponentProvisioningRootProgress {
59    pub fleet_subnet_root: Principal,
60    pub component_count: u32,
61    pub reserved_component_count: u32,
62    pub claimed_component_count: u32,
63    pub installed_component_count: u32,
64    pub registry_committed_component_count: u32,
65}
66
67/// Exact root-local Directory cursor copied from passive Coordinator status.
68#[derive(CandidType, Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
69#[serde(deny_unknown_fields)]
70pub struct FleetComponentPublicationRootProgress {
71    pub fleet_subnet_root: Principal,
72    pub component_count: u32,
73    pub published_component_count: u32,
74}
75
76/// Exact root-local runtime-activation cursor copied from passive Coordinator status.
77#[derive(CandidType, Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
78#[serde(deny_unknown_fields)]
79pub struct FleetComponentActivationRootProgress {
80    pub fleet_subnet_root: Principal,
81    pub component_count: u32,
82    pub activated_component_count: u32,
83    pub root_runtime_active: bool,
84}
85
86/// Exact passive lookup key for one Coordinator-owned provisioning operation.
87#[derive(CandidType, Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
88#[serde(deny_unknown_fields)]
89pub struct FleetComponentProvisioningStatusRequest {
90    pub operation_id: [u8; 32],
91    pub plan_hash: [u8; 32],
92}
93
94/// Durable Coordinator progress exposed without returning the complete plan.
95#[derive(CandidType, Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
96pub enum FleetComponentProvisioningPhase {
97    Planned,
98    AcceptingRoots,
99    RootsAccepted,
100    ProvisioningRoots,
101    ComponentsProvisioned,
102    ServiceTopologyPublished,
103    ConfirmingDirectories,
104    DirectoriesConfirmed,
105    ActivatingRuntimes,
106    RuntimesActivated,
107}
108
109/// Compact exact status for one Coordinator-owned provisioning operation.
110#[derive(CandidType, Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
111#[serde(deny_unknown_fields)]
112pub struct FleetComponentProvisioningStatusResponse {
113    pub operation_id: [u8; 32],
114    pub plan_hash: [u8; 32],
115    pub fleet_registry: FleetRegistryVersion,
116    pub configuration_digest: ComponentDeploymentConfigurationDigest,
117    pub operation: FleetComponentProvisioningOperation,
118    pub phase: FleetComponentProvisioningPhase,
119    pub directory_confirmation_root_count: u32,
120    pub root_batch_count: u32,
121    pub accepted_root_count: u32,
122    pub acceptance_in_flight_root: Option<Principal>,
123    pub provisioned_root_count: u32,
124    pub current_root: Option<FleetComponentProvisioningRootProgress>,
125    pub provisioning_in_flight_root: Option<Principal>,
126    pub directory_confirmed_root_count: u32,
127    pub current_publication: Option<FleetComponentPublicationRootProgress>,
128    pub publication_in_flight_root: Option<Principal>,
129    pub runtime_activated_root_count: u32,
130    pub current_activation: Option<FleetComponentActivationRootProgress>,
131    pub activation_in_flight_root: Option<Principal>,
132    pub group_placement_count: u32,
133    pub component_count: u32,
134    pub planned_at_ns: u64,
135    pub roots_accepted_at_ns: Option<u64>,
136    pub components_provisioned_at_ns: Option<u64>,
137    pub published_fleet_registry: Option<FleetRegistryVersion>,
138    pub service_topology_published_at_ns: Option<u64>,
139    pub directories_confirmed_at_ns: Option<u64>,
140    pub runtimes_activated_at_ns: Option<u64>,
141}
142
143/// Fresh-install or monotonic scale-out scope covered by one plan.
144#[derive(CandidType, Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
145#[serde(deny_unknown_fields)]
146pub enum FleetComponentProvisioningOperation {
147    FreshInstall,
148    ScaleOut {
149        deployment: ComponentGroupDeploymentId,
150        previous_placements: u32,
151        requested_placements: u32,
152    },
153}
154
155/// One selected root's complete canonical provisioning batch.
156#[derive(CandidType, Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
157#[serde(deny_unknown_fields)]
158pub struct FleetSubnetRootProvisioningBatch {
159    pub root: FleetSubnetRootBinding,
160    pub active_release_set: FleetSubnetRootReleaseSet,
161    pub placements: Vec<ComponentGroupPlacementPlan>,
162}
163
164/// One materialized copy of a completely flattened Component Group.
165#[derive(CandidType, Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
166#[serde(deny_unknown_fields)]
167pub struct ComponentGroupPlacementPlan {
168    pub group_placement: ComponentGroupPlacementId,
169    pub component_group: ComponentGroupSpecId,
170    pub entries: Vec<ComponentGroupPlanEntry>,
171}
172
173/// One exact top-level Component occurrence within a group placement.
174#[derive(CandidType, Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
175#[serde(deny_unknown_fields)]
176pub struct ComponentGroupPlanEntry {
177    pub member_path: ComponentGroupMemberPath,
178    pub component_spec: ComponentSpecId,
179    pub spec_hash: [u8; 32],
180    pub purpose: ComponentDeploymentPurpose,
181    pub labels: Vec<ComponentDeploymentLabel>,
182    pub limits: ComponentDeploymentLimits,
183}
184
185/// Coordinator-authenticated command asking one root to retain its exact plan batch.
186#[derive(CandidType, Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
187#[serde(deny_unknown_fields)]
188pub struct RootComponentProvisioningAcceptanceRequest {
189    pub fleet_registry: FleetRegistryVersion,
190    pub configuration_digest: ComponentDeploymentConfigurationDigest,
191    pub operation_id: [u8; 32],
192    pub plan_hash: [u8; 32],
193    pub batch: FleetSubnetRootProvisioningBatch,
194}
195
196/// Read-only lookup key for one exact root provisioning operation.
197#[derive(CandidType, Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
198#[serde(deny_unknown_fields)]
199pub struct RootComponentProvisioningStatusRequest {
200    pub operation_id: [u8; 32],
201    pub plan_hash: [u8; 32],
202}
203
204/// Coordinator-authenticated command advancing one exact bounded provisioning step.
205#[derive(CandidType, Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
206#[serde(deny_unknown_fields)]
207pub struct RootComponentProvisioningAdvanceRequest {
208    pub operation_id: [u8; 32],
209    pub plan_hash: [u8; 32],
210    pub expected_reserved_component_count: u32,
211    pub expected_claimed_component_count: u32,
212    pub expected_installed_component_count: u32,
213    pub expected_registry_committed_component_count: u32,
214}
215
216/// One exact member of a root-derived Component Group Directory.
217#[derive(CandidType, Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
218#[serde(deny_unknown_fields)]
219pub struct ComponentGroupDirectoryMember {
220    pub member_path: ComponentGroupMemberPath,
221    pub component_spec: ComponentSpecId,
222    pub purpose: ComponentDeploymentPurpose,
223    pub labels: Vec<ComponentDeploymentLabel>,
224    pub binding: ComponentBinding,
225}
226
227/// Protected origin of one root-derived Component Group Directory.
228#[derive(CandidType, Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
229#[serde(deny_unknown_fields)]
230pub struct ComponentGroupDirectoryProvenance {
231    pub authority: crate::ids::FleetRegistryAuthority,
232    pub fleet_subnet_root: Principal,
233    pub group_placement: ComponentGroupPlacementId,
234    pub component_group: ComponentGroupSpecId,
235    pub operation_id: [u8; 32],
236    pub plan_hash: [u8; 32],
237    pub placement_receipt_content_hash: [u8; 32],
238}
239
240/// Complete bounded sibling projection for one materialized Component Group placement.
241#[derive(CandidType, Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
242#[serde(deny_unknown_fields)]
243pub struct ComponentGroupDirectory {
244    pub provenance: ComponentGroupDirectoryProvenance,
245    pub members: Vec<ComponentGroupDirectoryMember>,
246}
247
248/// Compact proof of one exact Component Directory delivered during publication.
249#[derive(CandidType, Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
250#[serde(deny_unknown_fields)]
251pub struct ComponentDirectoryPublicationEvidence {
252    pub component: crate::ids::ComponentInstanceId,
253    pub content_hash: [u8; 32],
254}
255
256/// Compact proof of one exact Component Group Directory delivered during publication.
257#[derive(CandidType, Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
258#[serde(deny_unknown_fields)]
259pub struct ComponentGroupDirectoryPublicationEvidence {
260    pub group_placement: ComponentGroupPlacementId,
261    pub content_hash: [u8; 32],
262}
263
264/// Complete root-local evidence for one published provisioning batch.
265#[derive(CandidType, Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
266#[serde(deny_unknown_fields)]
267pub struct RootComponentPublicationEvidence {
268    pub fleet_registry: FleetRegistryVersion,
269    pub fleet_directory_content_hash: [u8; 32],
270    pub component_directories: Vec<ComponentDirectoryPublicationEvidence>,
271    pub component_group_directories: Vec<ComponentGroupDirectoryPublicationEvidence>,
272}
273
274/// Coordinator-authenticated command advancing one bounded root publication step.
275#[derive(CandidType, Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
276#[serde(deny_unknown_fields)]
277pub struct RootComponentPublicationRequest {
278    pub operation_id: [u8; 32],
279    pub plan_hash: [u8; 32],
280    pub published_fleet_registry: FleetRegistryVersion,
281    pub expected_published_component_count: u32,
282}
283
284///
285/// RootComponentDirectorySynchronizationRequest
286///
287/// Coordinator-authenticated command advancing one affected-root scale-out Directory step.
288///
289
290#[derive(CandidType, Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
291#[serde(deny_unknown_fields)]
292pub struct RootComponentDirectorySynchronizationRequest {
293    pub operation_id: [u8; 32],
294    pub plan_hash: [u8; 32],
295    pub source_fleet_registry: FleetRegistryVersion,
296    pub published_fleet_registry: FleetRegistryVersion,
297    pub expected_synchronized_component_count: u32,
298}
299
300///
301/// RootComponentDirectorySynchronizationResponse
302///
303/// Compact exact progress for one root's affected existing service members.
304///
305
306#[derive(CandidType, Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
307#[serde(deny_unknown_fields)]
308pub struct RootComponentDirectorySynchronizationResponse {
309    pub operation_id: [u8; 32],
310    pub plan_hash: [u8; 32],
311    pub source_fleet_registry: FleetRegistryVersion,
312    pub published_fleet_registry: FleetRegistryVersion,
313    pub fleet_subnet_root: Principal,
314    pub affected_component_count: u32,
315    pub synchronized_component_count: u32,
316    pub fleet_directory_content_hash: [u8; 32],
317    pub complete: bool,
318    pub synchronized_at_ns: Option<u64>,
319    pub receipt_content_hash: [u8; 32],
320}
321
322/// Coordinator-authenticated command advancing one bounded root activation step.
323#[derive(CandidType, Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
324#[serde(deny_unknown_fields)]
325pub struct RootComponentActivationRequest {
326    pub operation_id: [u8; 32],
327    pub plan_hash: [u8; 32],
328    pub expected_activated_component_count: u32,
329    pub expected_root_runtime_active: bool,
330}
331
332/// Compact terminal evidence binding Component inventory and root runtime activation.
333#[derive(CandidType, Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
334#[serde(deny_unknown_fields)]
335pub struct RootComponentActivationEvidence {
336    pub fleet_activation_operation_id: [u8; 32],
337    pub initial_inventory_hash: [u8; 32],
338    pub component_count: u32,
339    pub root_activated_at_ns: u64,
340}
341
342/// One exact provisioned Component occurrence and its committed Registry identity.
343#[derive(CandidType, Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
344#[serde(deny_unknown_fields)]
345pub struct RootProvisionedGroupMember {
346    pub member_path: ComponentGroupMemberPath,
347    pub component_spec: ComponentSpecId,
348    pub purpose: ComponentDeploymentPurpose,
349    pub limits: ComponentDeploymentLimits,
350    pub binding: ComponentBinding,
351    pub component_registry_revision: u64,
352    pub component_registry_content_hash: [u8; 32],
353}
354
355/// Complete provisioned result for one exact group placement on this root.
356#[derive(CandidType, Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
357#[serde(deny_unknown_fields)]
358pub struct RootProvisionedGroupPlacement {
359    pub group_placement: ComponentGroupPlacementId,
360    pub component_group: ComponentGroupSpecId,
361    pub members: Vec<RootProvisionedGroupMember>,
362}
363
364/// Complete group-partitioned result of one root provisioning operation.
365#[derive(CandidType, Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
366#[serde(deny_unknown_fields)]
367pub struct RootComponentProvisioningResult {
368    pub placements: Vec<RootProvisionedGroupPlacement>,
369}
370
371/// Durable aggregate progress of one root provisioning batch.
372#[derive(CandidType, Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
373pub enum RootComponentProvisioningPhase {
374    Accepted,
375    Provisioned,
376    Published,
377    RuntimesActive,
378}
379
380/// Durable progress or complete terminal result for one exact root provisioning operation.
381#[derive(CandidType, Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
382#[serde(deny_unknown_fields)]
383pub struct RootComponentProvisioningStatusResponse {
384    pub operation_id: [u8; 32],
385    pub plan_hash: [u8; 32],
386    pub fleet_registry: FleetRegistryVersion,
387    pub configuration_digest: ComponentDeploymentConfigurationDigest,
388    pub fleet_subnet_root: Principal,
389    pub phase: RootComponentProvisioningPhase,
390    pub placement_count: u32,
391    pub component_count: u32,
392    pub reserved_component_count: u32,
393    pub claimed_component_count: u32,
394    pub installed_component_count: u32,
395    pub registry_committed_component_count: u32,
396    pub published_component_count: u32,
397    pub activated_component_count: u32,
398    pub root_runtime_active: bool,
399    pub result: Option<RootComponentProvisioningResult>,
400    pub publication: Option<RootComponentPublicationEvidence>,
401    pub activation: Option<RootComponentActivationEvidence>,
402    pub accepted_at_ns: u64,
403    pub provisioned_at_ns: Option<u64>,
404    pub published_at_ns: Option<u64>,
405    pub activation_started_at_ns: Option<u64>,
406    pub runtimes_activated_at_ns: Option<u64>,
407    pub receipt_content_hash: [u8; 32],
408}
canic_core/dto/component_provisioning.rs

canic_core/dto/
component_provisioning.rs
