canic-core 0.110.35

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

//! Module: infra::ic::mgmt::status_settings
//!
//! Responsibility: perform raw Canister-history, status and settings management calls.
//! Does not own: status policy, deployment orchestration, or public DTO shaping.
//! Boundary: extends `MgmtInfra` with status and settings effects.

use crate::{
    cdk::candid::Principal,
    infra::ic::{
        IcInfraError,
        call::{Call, CallBuilder, CallResult},
    },
};

use super::{
    MgmtInfra,
    types::{
        InfraCanisterIdRecord, InfraCanisterInfoArgs, InfraCanisterInfoResult,
        InfraCanisterStatusResult, InfraUpdateSettingsArgs,
    },
};

impl MgmtInfra {
    /// Observe the latest history entry through a replicated management call.
    pub async fn canister_history(canister_pid: Principal) -> Result<CallResult, IcInfraError> {
        Call::bounded_wait(Principal::management_canister(), "canister_info")
            .with_arg(InfraCanisterInfoArgs {
                canister_id: canister_pid,
                num_requested_changes: Some(1),
            })?
            .execute()
            .await
    }

    /// Read one canister's monotonic management-history change count.
    pub async fn canister_history_total_changes(
        canister_pid: Principal,
    ) -> Result<u64, IcInfraError> {
        let args = InfraCanisterInfoArgs {
            canister_id: canister_pid,
            num_requested_changes: None,
        };
        let response = Call::bounded_wait(Principal::management_canister(), "canister_info")
            .with_arg(args)?
            .execute()
            .await?;
        let (info,): (InfraCanisterInfoResult,) = response.candid_tuple()?;
        Ok(info.total_num_changes)
    }

    /// Query the management canister for a canister's status.
    pub async fn canister_status(
        canister_pid: Principal,
    ) -> Result<InfraCanisterStatusResult, IcInfraError> {
        let response = canister_status_call(canister_pid)?.execute().await?;
        let (status,): (InfraCanisterStatusResult,) = response.candid_tuple()?;

        Ok(status)
    }

    /// Quote the same encoded status call without scheduling an outbound effect.
    pub fn canister_status_call_cost(canister_pid: Principal) -> Result<u128, IcInfraError> {
        Ok(canister_status_call(canister_pid)?.cost())
    }

    /// Update canister settings through the management canister.
    pub async fn update_settings(args: &InfraUpdateSettingsArgs) -> Result<(), IcInfraError> {
        Call::unbounded_wait(Principal::management_canister(), "update_settings")
            .with_arg(args.clone())?
            .execute()
            .await?;

        Ok(())
    }
}

fn canister_status_call(canister_pid: Principal) -> Result<CallBuilder<'static>, IcInfraError> {
    Call::bounded_wait(Principal::management_canister(), "canister_status").with_arg(
        InfraCanisterIdRecord {
            canister_id: canister_pid,
        },
    )
}