canic-core 0.104.2

Canic — a canister orchestration and management toolkit for the Internet Computer
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127

//! Module: workflow::runtime
//!
//! Responsibility: coordinate runtime startup services and memory initialization.
//! Does not own: lifecycle adapters, endpoint authorization, or stable schemas.
//! Boundary: lifecycle workflows call runtime startup after environment restore.

pub mod async_job;
pub mod auth;
pub mod authority_restore;
pub mod cycles;
pub mod fleet_activation;
pub mod install;
pub mod intent;
pub mod log;
mod nonroot;
mod root;
pub mod timer;

use crate::ops::storage::{
    icp_refill::IcpRefillStoreOps,
    intent::{IntentStoreOps, ReceiptBackedIntentOps},
};
use crate::{
    InternalError,
    log::Topic,
    ops::runtime::{env::EnvOps, memory::MemoryRegistryOps},
    workflow,
};

pub use nonroot::{
    init_local_nonroot_canister, init_local_nonroot_canister_with_automatic_topup,
    init_nonroot_canister, init_wasm_store_canister,
    post_upgrade_local_nonroot_canister_after_memory_init,
    post_upgrade_local_nonroot_canister_with_automatic_topup_after_memory_init,
    post_upgrade_nonroot_canister_after_memory_init,
    post_upgrade_nonroot_canister_with_automatic_topup_after_memory_init,
};
pub use root::{init_root_canister, post_upgrade_root_canister_after_memory_init};

///
/// RuntimeWorkflow
/// Coordinates periodic background services (timers) for Canic canisters.
///

pub struct RuntimeWorkflow;

impl RuntimeWorkflow {
    /// Start fixed runtime consumers shared by non-root profiles.
    pub fn start_all() -> Result<(), InternalError> {
        workflow::runtime::log::LogRetentionWorkflow::start()?;
        workflow::runtime::intent::IntentCleanupWorkflow::start()?;
        Ok(())
    }

    /// Start the shared consumers plus the compile-selected automatic top-up owner.
    pub fn start_all_with_automatic_topup() -> Result<(), InternalError> {
        Self::start_all()?;
        workflow::runtime::cycles::CycleWorkflow::start()
    }

    /// Start timers that should run only on root canisters.
    pub fn start_all_root() -> Result<(), InternalError> {
        EnvOps::require_root().map_err(|_err| InternalError::invariant())?;

        // Start shared runtime owners before root-only services.
        workflow::runtime::log::LogRetentionWorkflow::start()?;
        workflow::runtime::intent::IntentCleanupWorkflow::start()?;

        // root-only services
        workflow::runtime::auth::RuntimeAuthWorkflow::reconcile_root_issuer_renewal()?;
        Ok(())
    }
}

pub(super) fn log_memory_summary() {
    crate::log!(Topic::Memory, Info, "💾 memory.registry: bootstrapped");
}

fn init_post_upgrade_memory_registry() -> Result<(), InternalError> {
    MemoryRegistryOps::bootstrap_registry().map_err(|_err| InternalError::invariant())
}

pub fn init_memory_registry_post_upgrade() -> Result<(), InternalError> {
    init_post_upgrade_memory_registry()
}

pub(super) fn rebuild_derived_storage_indexes() -> Result<(), InternalError> {
    IntentStoreOps::rebuild_expiry_index()?;
    ReceiptBackedIntentOps::reconcile_receipt_indexes()?;
    let _receipt_capacity = ReceiptBackedIntentOps::receipt_capacity()?;

    Ok(())
}

pub(super) fn rebuild_root_derived_storage_indexes() -> Result<(), InternalError> {
    IcpRefillStoreOps::rebuild_indexes()?;
    rebuild_derived_storage_indexes()
}

pub(super) fn require_no_resumable_refill_for_upgrade() -> Result<(), InternalError> {
    validate_refill_upgrade_admission(IcpRefillStoreOps::resumable_operation_count())
}

const fn validate_refill_upgrade_admission(count: usize) -> Result<(), InternalError> {
    if count == 0 {
        return Ok(());
    }

    Err(InternalError::invariant())
}

#[cfg(test)]
mod tests {
    use super::validate_refill_upgrade_admission;

    #[test]
    fn root_upgrade_accepts_terminal_refill_state() {
        validate_refill_upgrade_admission(0).expect("terminal refill state should permit upgrade");
    }

    #[test]
    fn root_upgrade_rejects_resumable_refill_state() {
        let error = validate_refill_upgrade_admission(1)
            .expect_err("resumable refill state must block upgrade");
        assert_eq!(error.code(), crate::diagnostics::codes::STATE_INVALID);
    }
}