canic_host/install_root/
mod.rs

1use crate::{
2    canister_build::cache::DefaultCanisterBuildCacheCleanup,
3    release_set::{icp_root, workspace_root},
4};
5use config_selection::resolve_install_config_path;
6use std::{path::PathBuf, time::Instant};
7use thiserror::Error as ThisError;
8
9mod activation;
10mod artifact_promotion;
11mod build_environment;
12mod build_targets;
13mod capabilities;
14mod clock;
15mod commands;
16mod config_selection;
17mod current_execution;
18mod deployment_registration;
19mod deployment_truth_gate;
20mod execution_preflight;
21mod identity;
22mod install_state;
23mod operations;
24mod options;
25mod output;
26mod phase_receipts;
27mod plan_artifacts;
28mod preparation;
29mod readiness;
30mod receipt_io;
31mod root_canister;
32mod root_cycles;
33mod root_verification;
34mod staging;
35mod state;
36mod timing;
37mod truth_check;
38
39use activation::run_root_activation_phases;
40use artifact_promotion::write_artifact_promotion_execution_receipt_for_install;
41use build_environment::BuildEnvGuard;
42pub use config_selection::{
43    current_canic_project_root, discover_canic_config_choices, discover_canic_project_root_from,
44    discover_project_canic_config_choices, project_fleet_roots,
45};
46use current_execution::current_install_execution_context;
47pub use deployment_registration::{
48    RegisterDeploymentStateOptions, VerifyDeploymentRootOptions, register_deployment_state,
49    verify_registered_deployment_root,
50};
51use identity::resolve_install_identity;
52use install_state::{build_install_state, write_install_state_with_deployment_truth_receipt};
53pub use options::InstallRootOptions;
54use output::{print_install_result_summary, print_install_timing_summary};
55use phase_receipts::InstallReceiptScope;
56use plan_artifacts::emit_manifest_with_deployment_truth_receipt;
57use preparation::prepare_install_deployment_truth;
58pub use receipt_io::latest_deployment_truth_receipt_path_from_root;
59pub use state::{
60    InstallState, RootVerificationStatus, read_named_deployment_install_state,
61    read_named_deployment_install_state_from_root,
62};
63use timing::InstallTimingSummary as CurrentInstallTimingSummary;
64pub use truth_check::{check_install_deployment_truth, check_install_execution_preflight};
65
66#[cfg(test)]
67mod tests;
68
69///
70/// InstallRootBlockKind
71///
72/// Machine-readable reason that a fresh root install stopped before mutation.
73///
74
75#[derive(Clone, Copy, Debug, Eq, PartialEq)]
76pub enum InstallRootBlockKind {
77    DeploymentExecutionPreflight,
78    DeploymentTruth,
79}
80
81///
82/// InstallRootBlockedError
83///
84/// Typed install block retained through the host/CLI error boundary.
85///
86
87#[derive(Debug, ThisError)]
88#[error("{message}")]
89pub struct InstallRootBlockedError {
90    kind: InstallRootBlockKind,
91    message: String,
92}
93
94impl InstallRootBlockedError {
95    pub(super) const fn new(kind: InstallRootBlockKind, message: String) -> Self {
96        Self { kind, message }
97    }
98
99    #[must_use]
100    pub const fn kind(&self) -> InstallRootBlockKind {
101        self.kind
102    }
103}
104
105/// Discover installable Canic config choices under the current workspace.
106pub fn discover_current_canic_config_choices() -> Result<Vec<PathBuf>, Box<dyn std::error::Error>> {
107    let project_root = current_canic_project_root()?;
108    let choices = config_selection::discover_workspace_canic_config_choices(&project_root)?;
109    if !choices.is_empty() {
110        return Ok(choices);
111    }
112
113    if let Ok(icp_root) = icp_root()
114        && icp_root != project_root
115    {
116        return config_selection::discover_workspace_canic_config_choices(&icp_root);
117    }
118
119    Ok(choices)
120}
121
122// Execute the local thin-root install flow against an already running replica.
123pub fn install_root(options: InstallRootOptions) -> Result<(), Box<dyn std::error::Error>> {
124    let workspace_root = workspace_root()?;
125    let _build_cache_cleanup = DefaultCanisterBuildCacheCleanup::for_install(&workspace_root);
126    let icp_root = match &options.icp_root {
127        Some(path) => path.canonicalize()?,
128        None => icp_root()?,
129    };
130    let config_path = resolve_install_config_path(
131        &icp_root,
132        options.config_path.as_deref(),
133        options.interactive_config_selection,
134    )?;
135    let _install_env = BuildEnvGuard::apply(&options.network, &config_path, &icp_root);
136    let (fleet_name, deployment_name) = resolve_install_identity(&options, &config_path)?;
137    let total_started_at = Instant::now();
138    let mut timings = CurrentInstallTimingSummary::default();
139    let network = options.network.as_str();
140    let execution_context = current_install_execution_context(&workspace_root, &icp_root, network);
141
142    println!("Installing deployment {deployment_name}");
143    println!("Fleet template {fleet_name}");
144    println!();
145    let prepared = prepare_install_deployment_truth(
146        &options,
147        &workspace_root,
148        &icp_root,
149        &config_path,
150        &deployment_name,
151        &execution_context,
152    )?;
153    timings.create_canisters = prepared.timings.create_canisters;
154    timings.build_all = prepared.timings.build_all;
155
156    let (manifest_path, emit_manifest_duration) = emit_manifest_with_deployment_truth_receipt(
157        &workspace_root,
158        &icp_root,
159        &options,
160        &config_path,
161        &deployment_name,
162        &prepared.deployment_truth_check,
163        &execution_context,
164    )?;
165    timings.emit_manifest = emit_manifest_duration;
166    let activation_timings = run_root_activation_phases(
167        InstallReceiptScope {
168            icp_root: &icp_root,
169            network,
170            deployment_name: &deployment_name,
171            check: &prepared.deployment_truth_check,
172            execution_context: Some(&execution_context),
173        },
174        &options,
175        &prepared.root_canister_id,
176        &manifest_path,
177        total_started_at,
178    )?;
179    timings.install_root = activation_timings.install_root;
180    timings.fund_root = activation_timings.fund_root;
181    timings.stage_release_set = activation_timings.stage_release_set;
182    timings.resume_bootstrap = activation_timings.resume_bootstrap;
183    timings.wait_ready = activation_timings.wait_ready;
184    timings.finalize_root_funding = activation_timings.finalize_root_funding;
185
186    print_install_timing_summary(&timings, total_started_at.elapsed());
187    let state = build_install_state(
188        &options,
189        &workspace_root,
190        &icp_root,
191        &config_path,
192        &manifest_path,
193        (&deployment_name, &fleet_name),
194        &prepared.root_canister_id,
195    )?;
196    let state_path = write_install_state_with_deployment_truth_receipt(
197        InstallReceiptScope {
198            icp_root: &icp_root,
199            network,
200            deployment_name: &deployment_name,
201            check: &prepared.deployment_truth_check,
202            execution_context: Some(&execution_context),
203        },
204        &options.network,
205        &state,
206    )?;
207    write_artifact_promotion_execution_receipt_for_install(
208        &options,
209        &icp_root,
210        network,
211        &deployment_name,
212        &prepared.deployment_truth_check,
213        &execution_context,
214    )?;
215    print_install_result_summary(
216        &options.network,
217        &state.deployment_name,
218        &state.fleet_template,
219        &state_path,
220    );
221    Ok(())
222}
canic_host/install_root/mod.rs

canic_host/install_root/
mod.rs
