canic-core 0.98.14

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

//! Module: ops::ic::mgmt
//!
//! Responsibility: expose observable IC management canister calls.
//! Does not own: canister lifecycle policy, placement decisions, or endpoint DTOs.
//! Boundary: records metrics and delegates management call mechanics to infra.

mod cycles;
mod lifecycle;
mod signing;
mod status_settings;
mod types;

use crate::{
    InternalError,
    domain::metrics::{
        ManagementCallMetricOperation, ManagementCallMetricOutcome, ManagementCallMetricReason,
        PlatformCallMetricMode, PlatformCallMetricOutcome, PlatformCallMetricReason,
        PlatformCallMetricSurface,
    },
    dto::canister::{
        CanisterSettings as CanisterSettingsDto, CanisterStatusResponse,
        EnvironmentVariable as EnvironmentVariableDto, MemoryMetrics, QueryStats,
    },
    ids::SystemMetricKind,
    infra::{InfraError, ic::mgmt::MgmtInfra},
    ops::{
        ic::IcOpsError,
        prelude::*,
        runtime::metrics::{
            management_call::ManagementCallMetrics, platform_call::PlatformCallMetrics,
            system::SystemMetrics,
        },
    },
};
use std::future::Future;

#[expect(
    unused_imports,
    reason = "part of the public management ops type surface"
)]
pub use types::UpgradeFlags;
pub use types::{
    CanisterInstallMode, CanisterSettings, CanisterSettingsSnapshot, CanisterStatus, EcdsaKeyId,
    EcdsaPublicKeyArgs, EcdsaPublicKeyResult, EnvironmentVariable, MemoryMetricsSnapshot,
    QueryStatsSnapshot, SignWithEcdsaArgs, SignWithEcdsaResult, UpdateSettingsArgs,
};
#[expect(
    unused_imports,
    reason = "preserves public management ops value paths while domain owns the values"
)]
pub use types::{CanisterStatusType, LogVisibility};

use types::{
    canister_status_from_infra, ecdsa_public_key_args_to_infra, ecdsa_public_key_from_infra,
    install_mode_to_infra, sign_with_ecdsa_args_to_infra, sign_with_ecdsa_from_infra,
    update_settings_to_infra,
};

///
/// MgmtOps
///
/// Operations-layer facade for IC management canister calls.
///

pub struct MgmtOps;

// Execute one management-canister call and record low-cardinality outcomes.
async fn management_call<T>(
    operation: ManagementCallMetricOperation,
    fut: impl Future<Output = Result<T, InfraError>>,
) -> Result<T, InternalError> {
    record_management_call(
        operation,
        PlatformCallMetricOutcome::Started,
        PlatformCallMetricReason::Ok,
        ManagementCallMetricOutcome::Started,
        ManagementCallMetricReason::Ok,
    );

    match fut.await {
        Ok(value) => {
            record_management_call(
                operation,
                PlatformCallMetricOutcome::Completed,
                PlatformCallMetricReason::Ok,
                ManagementCallMetricOutcome::Completed,
                ManagementCallMetricReason::Ok,
            );
            Ok(value)
        }
        Err(err) => {
            record_management_call(
                operation,
                PlatformCallMetricOutcome::Failed,
                PlatformCallMetricReason::Infra,
                ManagementCallMetricOutcome::Failed,
                ManagementCallMetricReason::Infra,
            );
            Err(IcOpsError::from(err).into())
        }
    }
}

// Record management-call metrics with no target or method labels.
fn record_management_call(
    operation: ManagementCallMetricOperation,
    platform_outcome: PlatformCallMetricOutcome,
    platform_reason: PlatformCallMetricReason,
    management_outcome: ManagementCallMetricOutcome,
    management_reason: ManagementCallMetricReason,
) {
    PlatformCallMetrics::record(
        PlatformCallMetricSurface::Management,
        PlatformCallMetricMode::Update,
        platform_outcome,
        platform_reason,
    );
    ManagementCallMetrics::record(operation, management_outcome, management_reason);
}