canic-testkit 0.24.7

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

use candid::encode_args;
use canic::{
    dto::{
        abi::v1::CanisterInitPayload,
        env::EnvBootstrapArgs,
        topology::{AppDirectoryArgs, SubnetDirectoryArgs},
    },
    ids::{CanisterRole, SubnetRole},
};
use std::{
    path::{Path, PathBuf},
    sync::Mutex,
};

use crate::{
    Fake,
    artifacts::{
        WasmBuildProfile, build_wasm_canisters, read_wasm, test_target_dir, wasm_artifacts_ready,
        workspace_root_for,
    },
};

use super::{Pic, PicSerialGuard, acquire_pic_serial_guard, pic};

const STANDALONE_INSTALL_CYCLES: u128 = 1_000_000_000_000;
const STANDALONE_READY_TICK_LIMIT: usize = 60;
static STANDALONE_BUILD_SERIAL: Mutex<()> = Mutex::new(());

///
/// StandaloneCanisterFixture
///

pub struct StandaloneCanisterFixture {
    pub pic: Pic,
    pub canister_id: canic::cdk::types::Principal,
    _serial_guard: PicSerialGuard,
}

// Install one non-root Canic canister into a fresh PocketIC instance with
// explicit local env bootstrap fields and no hierarchy directories.
#[must_use]
pub fn install_standalone_canister(
    crate_name: &str,
    role: CanisterRole,
    profile: WasmBuildProfile,
) -> StandaloneCanisterFixture {
    assert!(
        !role.is_root(),
        "standalone helper is for non-root canisters"
    );

    let workspace_root = workspace_root();
    let target_name = format!("standalone-{crate_name}");
    let target_dir = test_target_dir(&workspace_root, &target_name);
    ensure_canister_wasm_ready(&workspace_root, &target_dir, crate_name, profile);

    let wasm = read_wasm(&target_dir, crate_name, profile);
    let serial_guard = acquire_pic_serial_guard();
    let pic = pic();
    let canister_id = pic.create_canister();
    pic.add_cycles(canister_id, STANDALONE_INSTALL_CYCLES);
    pic.install_canister(canister_id, wasm, standalone_init_args(role), None);
    pic.wait_for_ready(
        canister_id,
        STANDALONE_READY_TICK_LIMIT,
        "standalone canister bootstrap",
    );

    StandaloneCanisterFixture {
        pic,
        canister_id,
        _serial_guard: serial_guard,
    }
}

// Build the requested wasm artifact once when it is missing from the shared
// standalone target directory.
fn ensure_canister_wasm_ready(
    workspace_root: &Path,
    target_dir: &Path,
    crate_name: &str,
    profile: WasmBuildProfile,
) {
    let _build_guard = STANDALONE_BUILD_SERIAL
        .lock()
        .unwrap_or_else(std::sync::PoisonError::into_inner);

    if wasm_artifacts_ready(target_dir, &[crate_name], profile) {
        return;
    }

    build_wasm_canisters(workspace_root, target_dir, &[crate_name], profile, &[]);
}

// Encode one explicit local non-root init payload without any hierarchy
// directory snapshots.
fn standalone_init_args(role: CanisterRole) -> Vec<u8> {
    let root_pid = Fake::principal(1);
    let payload = CanisterInitPayload {
        env: EnvBootstrapArgs {
            prime_root_pid: Some(root_pid),
            subnet_role: Some(SubnetRole::PRIME),
            subnet_pid: Some(Fake::principal(2)),
            root_pid: Some(root_pid),
            canister_role: Some(role),
            parent_pid: Some(root_pid),
        },
        app_directory: AppDirectoryArgs(Vec::new()),
        subnet_directory: SubnetDirectoryArgs(Vec::new()),
    };

    encode_args::<(CanisterInitPayload, Option<Vec<u8>>)>((payload, None))
        .expect("encode standalone init args")
}

fn workspace_root() -> PathBuf {
    workspace_root_for(env!("CARGO_MANIFEST_DIR"))
}